@wilnertech/halopsa-mcp-server 1.0.0

package/.env.example

@@ -0,0 +1,19 @@
+# HaloPSA MCP Server Environment Configuration
+# Copy this file to .env and fill in your actual values
+# NEVER commit the .env file to git
+
+# HaloPSA OAuth2 Client ID (required)
+# Get from: HaloPSA > Configuration > Integrations > API Applications
+HALOPSA_CLIENT_ID=your-client-id-here
+
+# HaloPSA OAuth2 Client Secret (required)
+HALOPSA_CLIENT_SECRET=your-client-secret-here
+
+# HaloPSA Base URL (optional)
+# Default: https://support.wilnertech.com
+# Change if using a different HaloPSA instance
+HALOPSA_BASE_URL=https://support.wilnertech.com
+
+# Test Client ID (required for smoke tests only)
+# A client ID to scope test resource creation/cleanup
+# HALOPSA_TEST_CLIENT_ID=123

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WilnerTech
+
+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,270 @@
+# HaloPSA MCP Server
+
+Model Context Protocol server for HaloPSA API integration - WilnerTech billing backbone.
+
+## Critical Business Context
+
+**HaloPSA is WilnerTech's billing backbone.** Asset and user counts are automatically pulled from HaloPSA for billing calculations.
+
+- **Accurate data = Accurate billing = Revenue protection**
+- **Duplicates = Billing errors = Revenue loss**
+- **Only ACTIVE assets (status_id=1) count toward billing**
+- **Only ACTIVE users (inactive=false) count toward billing**
+
+## Features
+
+- 31 tools for managing HaloPSA data
+- OAuth2 Client Credentials authentication with automatic token refresh
+- Rate limiting with exponential backoff (60 requests/minute)
+- In-memory caching with configurable TTLs
+- Token optimization via format_options (compact/standard/detailed modes)
+- Deduplication tools with confidence scoring
+- Custom field inspection for assets
+
+## Installation
+
+```bash
+cd .claude/mcp-servers/halopsa
+npm install
+npm run build
+```
+
+## Configuration
+
+### HaloPSA API Agent Setup (Security Best Practice)
+
+**WilnerTech uses a dedicated API-only agent for Claude MCP integration** following HaloPSA security best practices:
+
+1. **Create Dedicated Agent in HaloPSA:**
+   - Navigate to: Configuration > Agents & Teams > Agents
+   - Create new agent: `claude_mcp` (API-only account)
+   - Agent Type: API Only
+   - Status: Active
+   - Generate OAuth2 Client Credentials
+
+2. **Security Benefits:**
+   - **Audit Trail:** All API actions appear under `claude_mcp` agent in HaloPSA audit logs
+   - **Principle of Least Privilege:** Grant only necessary permissions (read-only for Phase 1)
+   - **Easy Revocation:** Disable `claude_mcp` agent to immediately terminate MCP access
+   - **No Personal Credential Exposure:** Keeps personal HaloPSA accounts separate from automation
+
+3. **Configure Permissions (Minimal Approach):**
+
+   **Phase 1 - Read-Only Inspection (✅ Current):**
+   - `read:assets` - Asset inspection, custom field analysis, deduplication
+   - `read:customers` - User/site/client inspection and deduplication (includes sites and clients)
+
+   **What Works with Phase 1 Permissions:**
+   - ✅ All asset inspection tools (list, search, get, batch)
+   - ✅ Asset deduplication tools (find matches, scan duplicates)
+   - ✅ Custom field analysis tools
+   - ✅ All user/site/client inspection tools
+   - ✅ User/site deduplication tools
+   - ✅ Reference data tools (asset types, statuses)
+
+   **Phase 2 - Write Operations (When Ready):**
+   - `edit:assets` - Enables create/update/delete asset operations (3 tools)
+   - `edit:customers` - Enables create/update user/site operations (4 tools)
+
+   **Note:** Start minimal and expand permissions as needed. All 31 tools are implemented; write operations will return permission errors until Phase 2 permissions are granted.
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `HALOPSA_CLIENT_ID` | Yes | OAuth2 Client ID from `claude_mcp` agent |
+| `HALOPSA_CLIENT_SECRET` | Yes | OAuth2 Client Secret from `claude_mcp` agent |
+| `HALOPSA_BASE_URL` | No | API base URL (default: `https://support.wilnertech.com`) |
+
+**Credential Storage:** Store credentials in ITGlue under:
+- Location: `Wilner Tech Org > 06 - Authentication - Encryption Keys`
+- Name: `API - HaloPSA - claude_mcp Agent`
+- Fields:
+  - Username: OAuth2 Client ID
+  - Password: OAuth2 Client Secret
+  - URL: `https://support.wilnertech.com`
+
+### Claude Desktop Configuration
+
+Add to `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "halopsa": {
+      "command": "node",
+      "args": ["C:/Users/ywilner/OneDrive - Wilner Tech Inc/Documents/WTECH - Script Repository/.claude/mcp-servers/halopsa/dist/index.js"],
+      "env": {
+        "HALOPSA_CLIENT_ID": "claude_mcp_client_id_here",
+        "HALOPSA_CLIENT_SECRET": "claude_mcp_client_secret_here",
+        "HALOPSA_BASE_URL": "https://support.wilnertech.com"
+      }
+    }
+  }
+}
+```
+
+**Security Note:** These credentials are for the dedicated `claude_mcp` agent, not personal credentials. All actions are audited under the `claude_mcp` agent in HaloPSA.
+
+## Tools Reference
+
+### Asset Tools (11)
+
+| Tool | Description |
+|------|-------------|
+| `list_halopsa_assets` | List assets with filtering, caching (1min TTL) |
+| `get_halopsa_asset` | Get single asset with custom fields |
+| `search_halopsa_assets_by_serial` | Search by serial number (key_field) |
+| `search_halopsa_assets_by_hostname` | Search by hostname (key_field2) |
+| `create_halopsa_asset` | Create new asset |
+| `update_halopsa_asset` | Update existing asset |
+| `delete_halopsa_asset` | Delete asset |
+| `list_halopsa_asset_custom_fields` | Inspect custom fields for an asset |
+| `get_halopsa_asset_field_schema` | Analyze custom field definitions |
+| `find_halopsa_asset_match` | Deduplication with confidence scoring |
+| `scan_halopsa_asset_duplicates` | Scan for duplicate assets |
+
+### User Tools (7)
+
+| Tool | Description |
+|------|-------------|
+| `list_halopsa_users` | List users with filtering, caching (1min TTL) |
+| `get_halopsa_user` | Get single user with custom fields |
+| `search_halopsa_users_by_email` | Search by email address |
+| `create_halopsa_user` | Create new user |
+| `update_halopsa_user` | Update existing user |
+| `find_halopsa_user_match` | Deduplication with confidence scoring |
+| `scan_halopsa_user_duplicates` | Scan for duplicate users |
+
+### Site Tools (4)
+
+| Tool | Description |
+|------|-------------|
+| `list_halopsa_sites` | List sites with caching (5min TTL) |
+| `get_halopsa_site` | Get single site |
+| `create_halopsa_site` | Create new site |
+| `find_halopsa_site_match` | Deduplication with fuzzy matching |
+
+### Client Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `list_halopsa_clients` | List clients with caching (5min TTL) |
+| `get_halopsa_client` | Get single client |
+| `search_halopsa_clients` | Search clients by name |
+
+### Reference Data Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `list_halopsa_asset_types` | List asset types (1hr cache) |
+| `list_halopsa_asset_statuses` | List statuses with billing notes |
+| `list_halopsa_contact_types` | List contact types (1hr cache) |
+
+### Batch Operations Tools (3)
+
+| Tool | Description |
+|------|-------------|
+| `get_halopsa_assets_batch` | Get multiple assets (max 50) |
+| `get_halopsa_users_batch` | Get multiple users (max 50) |
+| `get_halopsa_sites_batch` | Get multiple sites (max 50) |
+
+## Deduplication Algorithms
+
+### Asset Deduplication
+
+| Match Type | Confidence | Action |
+|------------|------------|--------|
+| Exact serial number | 100% | Auto-update |
+| Hostname only (serial mismatch) | 85% | Manual review |
+| No match | 0% | Create new |
+
+### User Deduplication
+
+| Match Type | Confidence | Action |
+|------------|------------|--------|
+| Exact email | 100% | Auto-update |
+| UPN match (Entra) | 95% | Auto-update |
+| Username only | 70% | Manual review |
+| No match | 0% | Create new |
+
+### Site Deduplication
+
+| Match Type | Confidence | Action |
+|------------|------------|--------|
+| Exact name | 100% | Auto-update |
+| Fuzzy name + address | 95% | Auto-update |
+| Fuzzy name only | 85% | Manual review |
+| No match | 0% | Create new |
+
+## Caching TTLs
+
+| Data Type | TTL | Rationale |
+|-----------|-----|-----------|
+| Assets | 1 min | Billing-critical, frequent changes |
+| Users | 1 min | Billing-critical, frequent changes |
+| Sites | 5 min | Moderate change rate |
+| Clients | 5 min | Moderate change rate |
+| Reference data | 1 hour | Rarely changes |
+
+## Token Optimization
+
+All tools support `format_options` for reducing response size:
+
+```json
+{
+  "format_options": {
+    "format": "compact",
+    "fields": ["id", "name", "status_id"],
+    "omit_empty": true
+  }
+}
+```
+
+**Formats:**
+- `compact`: Minimal fields (id, name, status)
+- `standard`: Default fields (no pretty-printing)
+- `detailed`: All fields with pretty-printing
+
+## Rate Limiting
+
+- **Limit:** 60 requests/minute per client_id
+- **Auto-throttling:** 1 second minimum between requests
+- **Retry:** Exponential backoff on 429 errors (1s, 2s, 4s)
+- **Token refresh:** 5 minutes before expiration
+
+## Error Handling
+
+The server provides detailed error responses:
+
+```json
+{
+  "error": true,
+  "error_type": "RateLimitExceeded",
+  "message": "HaloPSA API rate limit exceeded",
+  "details": {
+    "retry_after_seconds": 30
+  },
+  "suggestion": "Wait 30 seconds before retrying."
+}
+```
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Start server
+npm start
+```
+
+## Related Documentation
+
+- [HaloPSA API Documentation](/.claude/api-docs/halopsa.md)
+- [HaloPSA API Agent](/.claude/agents/halopsa-api-agent.md)
+- [ITGlue MCP Server](/.claude/mcp-servers/itglue/) (reference implementation)
+- [Official HaloPSA API Docs](https://halo.haloservicedesk.com/apidoc/index.html)

package/dist/api/client.d.ts

@@ -0,0 +1,85 @@
+/**
+ * HaloPSA API Client with OAuth2 authentication, rate limiting, and caching
+ * Implements exponential backoff for rate limits and auto-refresh for tokens
+ */
+export interface HaloPSAClientConfig {
+    clientId: string;
+    clientSecret: string;
+    baseUrl: string;
+    maxRetries?: number;
+    retryDelay?: number;
+}
+interface CacheOptions {
+    enabled?: boolean;
+    ttl?: number;
+    keyPrefix?: string;
+}
+export declare class HaloPSAAPIClient {
+    private client;
+    private authClient;
+    private clientId;
+    private clientSecret;
+    private baseUrl;
+    private maxRetries;
+    private retryDelay;
+    private accessToken;
+    private tokenExpiresAt;
+    private tokenRefreshBuffer;
+    private requestCount;
+    private lastRequestTime;
+    private readonly MIN_REQUEST_INTERVAL;
+    private inflight;
+    constructor(config: HaloPSAClientConfig);
+    /**
+     * Ensure we have a valid access token
+     * Requests new token if none exists or if close to expiration
+     */
+    private ensureValidToken;
+    /**
+     * Request a new access token from HaloPSA
+     */
+    private refreshToken;
+    /**
+     * Throttle requests to respect rate limits (60 requests/minute)
+     * Updates lastRequestTime BEFORE delay to prevent race conditions with concurrent requests
+     */
+    private throttleRequest;
+    /**
+     * Handle API errors with retry logic for rate limits and token expiration
+     */
+    private handleError;
+    /**
+     * Make a GET request with retry logic
+     */
+    get<T>(endpoint: string, params?: Record<string, unknown>, retryCount?: number): Promise<T>;
+    /**
+     * Make a GET request with caching support
+     */
+    getCached<T>(endpoint: string, params?: Record<string, unknown>, cacheOptions?: CacheOptions): Promise<T>;
+    /**
+     * Invalidate cache for specific patterns
+     */
+    invalidateCache(pattern: string): number;
+    /**
+     * Make a POST request with retry logic
+     */
+    post<T>(endpoint: string, data: unknown, retryCount?: number): Promise<T>;
+    /**
+     * Make a DELETE request with retry logic
+     */
+    delete<T>(endpoint: string, retryCount?: number): Promise<T>;
+    /**
+     * Check if error is retryable
+     */
+    private isRetryableError;
+    /**
+     * Get request statistics
+     */
+    getStats(): {
+        requestCount: number;
+        lastRequestTime: number;
+        tokenExpiresAt: number;
+    };
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AASD,UAAU,YAAY;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAG3B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,kBAAkB,CAAyB;IAGnD,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,eAAe,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAQ;IAG7C,OAAO,CAAC,QAAQ,CAA4C;gBAEhD,MAAM,EAAE,mBAAmB;IA+CvC;;;OAGG;YACW,gBAAgB;IAS9B;;OAEG;YACW,YAAY;IA0C1B;;;OAGG;YACW,eAAe;IAiB7B;;OAEG;YACW,WAAW;IAsDzB;;OAEG;IACG,GAAG,CAAC,CAAC,EACT,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,UAAU,SAAI,GACb,OAAO,CAAC,CAAC,CAAC;IAiBb;;OAEG;IACG,SAAS,CAAC,CAAC,EACf,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,CAAC,CAAC;IAqCb;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAIxC;;OAEG;IACG,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,SAAI,GAAG,OAAO,CAAC,CAAC,CAAC;IAiB1E;;OAEG;IACG,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,SAAI,GAAG,OAAO,CAAC,CAAC,CAAC;IAiB7D;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAiBxB;;OAEG;IACH,QAAQ,IAAI;QACV,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,MAAM,CAAC;QACxB,cAAc,EAAE,MAAM,CAAC;KACxB;CAOF"}

package/dist/api/client.js

@@ -0,0 +1,297 @@
+/**
+ * HaloPSA API Client with OAuth2 authentication, rate limiting, and caching
+ * Implements exponential backoff for rate limits and auto-refresh for tokens
+ */
+import axios from 'axios';
+import { globalCache, generateCacheKey, TTL } from '../cache/memory-cache.js';
+import { parseHaloPSAApiError, createNetworkError, createAuthError, HaloPSAError, } from './errors.js';
+export class HaloPSAAPIClient {
+    client;
+    authClient;
+    clientId;
+    clientSecret;
+    baseUrl;
+    maxRetries;
+    retryDelay;
+    // Token management
+    accessToken = null;
+    tokenExpiresAt = 0;
+    tokenRefreshBuffer = 2 * 60 * 1000; // Refresh 2 minutes before expiration
+    // Rate limiting
+    requestCount = 0;
+    lastRequestTime = 0;
+    MIN_REQUEST_INTERVAL = 1000; // 1 second between requests (60/min limit)
+    // Inflight request deduplication
+    inflight = new Map();
+    constructor(config) {
+        this.clientId = config.clientId;
+        this.clientSecret = config.clientSecret;
+        this.baseUrl = config.baseUrl;
+        this.maxRetries = config.maxRetries ?? 3;
+        this.retryDelay = config.retryDelay ?? 1000;
+        // Create auth client (for token requests)
+        // Auth server is at: baseUrl/auth (e.g., https://support.wilnertech.com/auth)
+        this.authClient = axios.create({
+            baseURL: `${this.baseUrl}/auth`,
+            timeout: 30000,
+        });
+        // Create API client (for data requests)
+        // Resource server is at: baseUrl/api (e.g., https://support.wilnertech.com/api)
+        this.client = axios.create({
+            baseURL: `${this.baseUrl}/api`,
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            timeout: 30000,
+        });
+        // Add request interceptor for authentication and rate limiting
+        this.client.interceptors.request.use(async (config) => {
+            // Ensure we have a valid token
+            await this.ensureValidToken();
+            // Add authorization header
+            config.headers.Authorization = `Bearer ${this.accessToken}`;
+            // Throttle requests to respect rate limits
+            await this.throttleRequest();
+            return config;
+        });
+        // Add response interceptor for error handling
+        this.client.interceptors.response.use((response) => response, async (error) => {
+            return this.handleError(error);
+        });
+    }
+    /**
+     * Ensure we have a valid access token
+     * Requests new token if none exists or if close to expiration
+     */
+    async ensureValidToken() {
+        const now = Date.now();
+        // Check if token is missing or expired (with buffer)
+        if (!this.accessToken || now >= this.tokenExpiresAt - this.tokenRefreshBuffer) {
+            await this.refreshToken();
+        }
+    }
+    /**
+     * Request a new access token from HaloPSA
+     */
+    async refreshToken() {
+        try {
+            const params = new URLSearchParams();
+            params.append('grant_type', 'client_credentials');
+            params.append('client_id', this.clientId);
+            params.append('client_secret', this.clientSecret);
+            params.append('scope', 'all');
+            const response = await this.authClient.post('/token', params, {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                },
+            });
+            this.accessToken = response.data.access_token;
+            // Calculate expiration time in milliseconds
+            this.tokenExpiresAt = Date.now() + response.data.expires_in * 1000;
+            console.error(`HaloPSA: New access token obtained. Expires at: ${new Date(this.tokenExpiresAt).toISOString()}`);
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                console.error('HaloPSA: Token refresh failed');
+                console.error(`HaloPSA: Request URL: ${error.config?.url}`);
+                console.error(`HaloPSA: Base URL: ${error.config?.baseURL}`);
+                console.error(`HaloPSA: Status: ${error.response?.status}`);
+                console.error(`HaloPSA: Response data:`, error.response?.data);
+                const message = error.response?.data?.error_description ||
+                    error.response?.data?.error ||
+                    error.message;
+                throw createAuthError(`Failed to obtain access token: ${message}`);
+            }
+            throw createAuthError('Failed to obtain access token');
+        }
+    }
+    /**
+     * Throttle requests to respect rate limits (60 requests/minute)
+     * Updates lastRequestTime BEFORE delay to prevent race conditions with concurrent requests
+     */
+    async throttleRequest() {
+        const now = Date.now();
+        const timeSinceLastRequest = now - this.lastRequestTime;
+        if (timeSinceLastRequest < this.MIN_REQUEST_INTERVAL) {
+            const delay = this.MIN_REQUEST_INTERVAL - timeSinceLastRequest;
+            // Update lastRequestTime BEFORE delay to prevent concurrent requests from calculating
+            // the same delay and firing simultaneously after waiting
+            this.lastRequestTime = now + delay;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+        else {
+            this.lastRequestTime = now;
+        }
+        this.requestCount++;
+    }
+    /**
+     * Handle API errors with retry logic for rate limits and token expiration
+     */
+    async handleError(error) {
+        // If error is already a HaloPSAError (e.g., from request interceptor), re-throw as-is
+        if (error instanceof HaloPSAError) {
+            throw error;
+        }
+        // Network error (no response from server)
+        if (!error.response) {
+            throw createNetworkError(error);
+        }
+        const status = error.response.status;
+        const data = error.response.data;
+        const endpoint = error.config?.url || 'unknown';
+        // Handle 401 - token may be expired
+        if (status === 401) {
+            // Clear token and retry once
+            this.accessToken = null;
+            this.tokenExpiresAt = 0;
+            // Don't retry if this was already a retry
+            if (error.config && !error.config.headers?.['X-Retry-Auth']) {
+                try {
+                    await this.ensureValidToken();
+                    error.config.headers = error.config.headers || {};
+                    error.config.headers['X-Retry-Auth'] = 'true';
+                    error.config.headers['Authorization'] = `Bearer ${this.accessToken}`;
+                    return this.client.request(error.config);
+                }
+                catch {
+                    // Token refresh failed, throw original error
+                }
+            }
+        }
+        // Handle 429 - rate limited
+        if (status === 429) {
+            const retryAfterHeader = error.response.headers['retry-after'];
+            const retryAfter = retryAfterHeader ? parseInt(retryAfterHeader, 10) : 30;
+            console.warn(`HaloPSA: Rate limited. Waiting ${retryAfter} seconds before retry...`);
+            await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
+            // Retry the request
+            if (error.config) {
+                return this.client.request(error.config);
+            }
+        }
+        // Parse and throw enhanced error
+        const enhancedError = parseHaloPSAApiError(status, data, endpoint);
+        throw enhancedError;
+    }
+    /**
+     * Make a GET request with retry logic
+     */
+    async get(endpoint, params, retryCount = 0) {
+        try {
+            const response = await this.client.get(endpoint, { params });
+            return response.data;
+        }
+        catch (error) {
+            if (retryCount < this.maxRetries && this.isRetryableError(error)) {
+                const delay = this.retryDelay * Math.pow(2, retryCount);
+                console.warn(`HaloPSA: Request failed. Retrying in ${delay}ms (attempt ${retryCount + 1}/${this.maxRetries})...`);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                return this.get(endpoint, params, retryCount + 1);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Make a GET request with caching support
+     */
+    async getCached(endpoint, params, cacheOptions) {
+        const { enabled = true, ttl = TTL.ASSET_LIST, keyPrefix = endpoint } = cacheOptions || {};
+        // Skip cache if disabled
+        if (!enabled) {
+            return this.get(endpoint, params);
+        }
+        // Generate cache key
+        const cacheKey = generateCacheKey(keyPrefix, params || {});
+        // Check cache first
+        const cachedValue = globalCache.get(cacheKey);
+        if (cachedValue !== null) {
+            return cachedValue;
+        }
+        // Inflight dedup — if an identical request is already in progress, share it
+        const existing = this.inflight.get(cacheKey);
+        if (existing) {
+            return existing;
+        }
+        // Fetch from API, cache result, and deduplicate concurrent requests
+        const promise = this.get(endpoint, params)
+            .then((result) => {
+            globalCache.set(cacheKey, result, ttl);
+            return result;
+        })
+            .finally(() => {
+            this.inflight.delete(cacheKey);
+        });
+        this.inflight.set(cacheKey, promise);
+        return promise;
+    }
+    /**
+     * Invalidate cache for specific patterns
+     */
+    invalidateCache(pattern) {
+        return globalCache.invalidatePattern(pattern);
+    }
+    /**
+     * Make a POST request with retry logic
+     */
+    async post(endpoint, data, retryCount = 0) {
+        try {
+            const response = await this.client.post(endpoint, data);
+            return response.data;
+        }
+        catch (error) {
+            if (retryCount < this.maxRetries && this.isRetryableError(error)) {
+                const delay = this.retryDelay * Math.pow(2, retryCount);
+                console.warn(`HaloPSA: Request failed. Retrying in ${delay}ms (attempt ${retryCount + 1}/${this.maxRetries})...`);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                return this.post(endpoint, data, retryCount + 1);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Make a DELETE request with retry logic
+     */
+    async delete(endpoint, retryCount = 0) {
+        try {
+            const response = await this.client.delete(endpoint);
+            return response.data;
+        }
+        catch (error) {
+            if (retryCount < this.maxRetries && this.isRetryableError(error)) {
+                const delay = this.retryDelay * Math.pow(2, retryCount);
+                console.warn(`HaloPSA: Request failed. Retrying in ${delay}ms (attempt ${retryCount + 1}/${this.maxRetries})...`);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                return this.delete(endpoint, retryCount + 1);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check if error is retryable
+     */
+    isRetryableError(error) {
+        if (error instanceof HaloPSAError) {
+            // Retry on rate limit and server errors
+            return (error.errorType === 'RateLimitExceeded' ||
+                error.errorType === 'ServerError' ||
+                error.errorType === 'NetworkError');
+        }
+        if (axios.isAxiosError(error)) {
+            const status = error.response?.status;
+            // Retry on 429 (rate limit), 500, 502, 503, 504 (server errors)
+            return status === 429 || (status !== undefined && status >= 500 && status <= 504);
+        }
+        return false;
+    }
+    /**
+     * Get request statistics
+     */
+    getStats() {
+        return {
+            requestCount: this.requestCount,
+            lastRequestTime: this.lastRequestTime,
+            tokenExpiresAt: this.tokenExpiresAt,
+        };
+    }
+}
+//# sourceMappingURL=client.js.map