@dangahagan/weather-mcp 1.6.1 → 1.7.1

package/README.md

@@ -30,6 +30,14 @@ An MCP (Model Context Protocol) server that provides **global weather data** to
   - Support for cities, airports, landmarks, and regions globally
   - Detailed metadata: timezone, elevation, population, country
   - Enables natural language queries: "What's the weather in Tokyo?"
+- **Saved Locations**: Save and reuse favorite locations (NEW in v1.7.0)
+  - Save frequently used locations with simple aliases ("home", "work", "cabin")
+  - Use saved locations by name instead of coordinates in all weather tools
+  - Tag locations with activities ("boating", "hiking", "skiing") for contextual weather info
+  - Automatic geocoding when saving (just provide location name)
+  - Persistent storage in `~/.weather-mcp/locations.json`
+  - Manage locations: save, list, view details, remove
+  - Makes queries natural: "What's the weather at home?" instead of providing coordinates
 - **Climate Normals - Historical Context**: Compare weather to 30-year averages (NEW in v1.2.0)
   - **Optional enhancement** for current conditions and forecasts (`include_normals=true`)
   - Shows normal high/low temperatures and precipitation for comparison
@@ -161,6 +169,28 @@ The cache automatically stores and retrieves weather data with intelligent expir
 
 ### Configuration
 
+**For most users: No configuration needed!** The server works out of the box with sensible defaults and requires no API keys.
+
+#### Optional: Environment Variables
+
+To customize server behavior, copy the example configuration file:
+
+```bash
+cp .env.example .env
+```
+
+Then edit `.env` to adjust settings as needed. See [`.env.example`](./.env.example) for comprehensive documentation on all available options.
+
+**What you can configure:**
+- **Tool Selection** - Choose which MCP tools to expose (basic/standard/full/all presets)
+- **Cache Settings** - Adjust cache size and enable/disable caching
+- **API Configuration** - Set request timeouts
+- **Logging** - Control log verbosity levels
+- **Optional API Tokens** - Add NCEI token for official US climate normals (falls back to free Open-Meteo data)
+- **Lightning Detection** - Configure alternative MQTT broker (optional)
+
+All settings have sensible defaults and can be omitted entirely.
+
 #### Tool Selection (NEW in v1.4.0)
 
 Control which MCP tools are exposed to reduce context overhead and customize functionality. By default, only **basic** tools are enabled.
@@ -169,25 +199,16 @@ Control which MCP tools are exposed to reduce context overhead and customize fun
 - `basic` (default): Essential weather tools (5 tools) - forecast, current_conditions, alerts, search_location, check_service_status
 - `standard`: Basic + historical_weather (6 tools)
 - `full`: Standard + air_quality (7 tools)
-- `all`: All available tools (12 tools) - includes marine_conditions, weather_imagery, lightning_activity, river_conditions, wildfire_info
+- `all`: All available tools (16 tools) - includes marine_conditions, weather_imagery, lightning_activity, river_conditions, wildfire_info, save_location, list_saved_locations, get_saved_location, remove_saved_location
 
 **Configuration Examples:**
 
 ```bash
-# Use a preset
-export ENABLED_TOOLS=full
-
-# Select specific tools
-export ENABLED_TOOLS=forecast,current,alerts,air_quality
-
-# Add tools to a preset
-export ENABLED_TOOLS=basic,+historical,+air_quality
-
-# Remove tools from a preset
-export ENABLED_TOOLS=all,-marine
-
-# Complex combinations
-export ENABLED_TOOLS=standard,+air_quality,-alerts
+# In .env file or MCP client config
+ENABLED_TOOLS=full                              # Use a preset
+ENABLED_TOOLS=forecast,current,alerts,air_quality  # Specific tools only
+ENABLED_TOOLS=basic,+historical,+air_quality   # Add to preset
+ENABLED_TOOLS=all,-marine                       # Remove from preset
 ```
 
 **Tool Aliases:**
@@ -198,20 +219,24 @@ Short names are supported: `forecast`, `current`, `conditions`, `alerts`, `warni
 - **Better Security**: Only expose necessary functionality
 - **Customization**: Tailor the server to your specific use case
 
-#### Cache Configuration
+#### MCP Client Configuration
 
-Caching is **enabled by default** with sensible settings. To customize:
+You can also set environment variables directly in your MCP client configuration file instead of using a `.env` file:
 
-```bash
-# Disable caching (not recommended)
-export CACHE_ENABLED=false
-
-# Adjust maximum cache size (default: 1000 entries)
-export CACHE_MAX_SIZE=1500
-
-# Optional: NOAA NCEI API token for official climate normals (US only, NEW in v1.2.0)
-# Falls back to Open-Meteo computed normals if not configured
-export NCEI_API_TOKEN=your_token_here
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "npx",
+      "args": ["-y", "@dangahagan/weather-mcp@latest"],
+      "env": {
+        "ENABLED_TOOLS": "full",
+        "CACHE_MAX_SIZE": "2000",
+        "LOG_LEVEL": "1"
+      }
+    }
+  }
+}
 ```
 
 **Note on Climate Normals (v1.2.0):**
@@ -220,6 +245,25 @@ export NCEI_API_TOKEN=your_token_here
 - Get a free token at: https://www.ncdc.noaa.gov/cdo-web/token
 - If NCEI token is configured but unavailable, the system automatically falls back to Open-Meteo
 
+#### Saved Locations (NEW in v1.7.0)
+
+The saved locations feature stores your favorite places (like "home", "work", "cabin") for easy reuse in weather queries. No configuration needed - it works automatically!
+
+**Storage Location:**
+- Data stored in: `~/.weather-mcp/locations.json`
+- Directory created automatically on first save
+- File is human-readable JSON (can be backed up or edited manually)
+
+**Features:**
+- No limit on number of saved locations
+- Tag locations with activities (e.g., "boating", "hiking") to help AI provide relevant weather info
+- Persistent across MCP server restarts
+- Portable - copy the file to migrate locations to another machine
+
+**Learn More:**
+- See [save_location](#13-save_location-new-in-v170) for usage instructions
+- See [Using Saved Locations](#using-saved-locations-with-weather-tools) for examples
+
 ### Monitoring
 
 Use the `check_service_status` tool to view cache statistics including:
@@ -268,7 +312,7 @@ If you prefer to build from source:
 
 1. Clone the repository:
 ```bash
-git clone https://github.com/dgahagan/weather-mcp.git
+git clone https://github.com/weather-mcp/weather-mcp.git
 cd weather-mcp
 ```
 
@@ -282,6 +326,14 @@ npm install
 npm run build
 ```
 
+4. (Optional) Configure environment variables:
+```bash
+cp .env.example .env
+# Edit .env to customize settings (all optional)
+```
+
+See the [Configuration](#configuration) section for details.
+
 ## Upgrading to Latest Version
 
 ### Upgrading npm Installation
@@ -333,7 +385,7 @@ npm run build
 You can verify your installed version by checking:
 - npm: `npm list -g @dangahagan/weather-mcp`
 - Source: `git describe --tags` or check `package.json`
-- Latest release: https://github.com/dgahagan/weather-mcp/releases
+- Latest release: https://github.com/weather-mcp/weather-mcp/releases
 
 ## Usage with AI Assistants
 
@@ -795,6 +847,136 @@ Provides critical wildfire monitoring and safety information using NIFC (Nationa
 
 **Note:** Data from NIFC WFIGS (Wildland Fire Interagency Geospatial Services). Always consult official sources for evacuation orders at https://inciweb.nwcg.gov/
 
+### 13. save_location (NEW in v1.7.0)
+Save a location with an alias for easy reuse in weather queries.
+
+**Parameters:**
+- `alias` (required): Short name for the location (e.g., "home", "work", "cabin"). Max 50 characters.
+- `location_query` (optional): Location to geocode and save (e.g., "Seattle, WA", "Paris, France"). Not required if latitude/longitude provided.
+- `latitude` (optional): Latitude if providing coordinates directly. Not required if location_query provided.
+- `longitude` (optional): Longitude if providing coordinates directly. Not required if location_query provided.
+- `name` (optional): Display name (required when using latitude/longitude directly)
+- `activities` (optional): Activities you do at this location (e.g., ["boating", "fishing"]). Helps AI provide relevant weather information. Each activity max 50 characters.
+
+**Description:**
+Saves a location to persistent storage (`~/.weather-mcp/locations.json`) for easy reuse. Accepts either a location query (which will be automatically geocoded using Nominatim/OpenStreetMap) or direct coordinates. Once saved, the location can be used in any weather tool by providing `location_name` instead of coordinates.
+
+**Smart Updates:** If the alias already exists and you only provide `name` and/or `activities` (without location details), it will update just those fields while preserving all coordinates and metadata. This makes it easy to add activities or rename locations without re-specifying the full address.
+
+**Examples:**
+```
+"Save my home location in Seattle, WA"
+  → save_location(alias="home", location_query="Seattle, WA")
+
+"Save the cabin at Lake Tahoe"
+  → save_location(alias="cabin", location_query="Lake Tahoe, CA")
+
+"Save coordinates 47.6062, -122.3321 as my office"
+  → save_location(alias="office", latitude=47.6062, longitude=-122.3321, name="Seattle Office")
+
+"Save the lake house where we go boating and fishing"
+  → save_location(alias="lake_house", location_query="Lake Tahoe, CA", activities=["boating", "fishing"])
+
+"Save my favorite hiking spot"
+  → save_location(alias="trail", location_query="Mt. Rainier, WA", activities=["hiking", "camping", "photography"])
+
+"Add more activities to the cabin" (smart update - no location needed)
+  → save_location(alias="cabin", activities=["boating", "fishing", "hiking", "swimming"])
+
+"Rename my campsite" (smart update - no location needed)
+  → save_location(alias="campsite", name="Yosemite Valley Campground")
+```
+
+**Returns:**
+- Confirmation of save with location details
+- Coordinates, timezone, and administrative region
+- Usage examples showing how to use with weather tools
+
+### 14. list_saved_locations (NEW in v1.7.0)
+View all saved locations.
+
+**Parameters:** None
+
+**Description:**
+Lists all locations saved in your persistent storage with their aliases, names, coordinates, and save dates. Helpful for seeing what location names are available for use with weather tools.
+
+**Examples:**
+```
+"Show my saved locations"
+"What locations do I have saved?"
+"List all my saved places"
+```
+
+**Returns:**
+- List of all saved locations with full details
+- Usage examples for each location
+- Total count of saved locations
+
+### 15. get_saved_location (NEW in v1.7.0)
+Get details for a specific saved location.
+
+**Parameters:**
+- `alias` (required): The name of the saved location to retrieve (e.g., "home", "work")
+
+**Description:**
+Retrieves detailed information about a specific saved location, including coordinates, timezone, region information, and save/update timestamps.
+
+**Examples:**
+```
+"Show details for my home location"
+"What are the coordinates for my cabin?"
+"Get info about my work location"
+```
+
+**Returns:**
+- Location name and coordinates
+- Timezone and administrative regions
+- Save and update timestamps
+- Usage examples
+
+### 16. remove_saved_location (NEW in v1.7.0)
+Remove a saved location.
+
+**Parameters:**
+- `alias` (required): The name of the saved location to remove (e.g., "home", "work")
+
+**Description:**
+Permanently removes a saved location from storage. The location data is deleted and can no longer be used with weather tools unless saved again.
+
+**Examples:**
+```
+"Remove my work location"
+"Delete the cabin from saved locations"
+"Remove home"
+```
+
+**Returns:**
+- Confirmation of removal
+- Count of remaining saved locations
+
+## Using Saved Locations with Weather Tools
+
+Once you've saved locations, you can use them with any weather tool by providing `location_name` instead of coordinates:
+
+**Examples:**
+```
+# Instead of:
+get_forecast(latitude=47.6062, longitude=-122.3321)
+
+# You can use:
+get_forecast(location_name="home")
+
+# Natural language queries work too:
+"What's the weather forecast at home?"
+"How's the air quality at my cabin?"
+"Are there any weather alerts for my work location?"
+```
+
+**Currently Supported Tools:**
+- `get_forecast` - Weather forecasts using saved locations
+
+**Coming Soon:** Support for saved locations in all weather tools (current conditions, alerts, air quality, marine conditions, etc.)
+
 ## Error Handling & Service Status
 
 ### Enhanced Error Messages
@@ -904,7 +1086,7 @@ npx tsx tests/test_noaa_api.ts
 
 ### Manual Testing with Claude Code
 
-See [TESTING_GUIDE.md](./docs/TESTING_GUIDE.md) for comprehensive manual testing instructions including:
+See [TESTING_GUIDE.md](./docs/testing/TESTING_GUIDE.md) for comprehensive manual testing instructions including:
 - Setup steps for MCP clients
 - Test cases for all tools
 - Error handling verification
@@ -1107,6 +1289,43 @@ To report a security vulnerability, please see our [Security Policy](./SECURITY.
 - Response timeline commitments (48hr acknowledgment, 7-day assessment)
 - Security best practices for users and developers
 
+## Documentation
+
+📚 **[Complete Documentation Index](./docs/README.md)** - Comprehensive navigation guide to all project documentation
+
+### Quick Links
+
+**For Users:**
+- [Client Setup Guide](./docs/CLIENT_SETUP.md) - Setup instructions for 8 different MCP clients
+- [Testing Guide](./docs/testing/TESTING_GUIDE.md) - Manual testing procedures
+- [Error Handling](./docs/ERROR_HANDLING.md) - Enhanced error handling features
+
+**For Developers:**
+- [Contributing Guidelines](./CONTRIBUTING.md) - How to contribute
+- [Development Guide](./CLAUDE.md) - AI assistant development guide
+- [Code Review](./docs/development/CODE_REVIEW.md) - Code quality analysis
+- [Security Audit](./docs/development/SECURITY_AUDIT_V1.6.md) - Security assessment
+
+**Planning & Roadmap:**
+- [Implementation Plan](./docs/planning/IMPLEMENTATION_PLAN.md) - Project roadmap
+- [Future Enhancements](./docs/planning/FUTURE_ENHANCEMENTS.md) - Planned features
+- [Roadmap](./docs/planning/ROADMAP.md) - Long-term plans
+
+**Testing & Quality:**
+- [Test Suite](./docs/testing/TEST_SUITE_README.md) - Test overview
+- [Test Coverage](./docs/testing/TEST_COVERAGE_ANALYSIS_2025.md) - Latest coverage analysis
+- [Test Recommendations](./docs/testing/TEST_RECOMMENDATIONS.md) - Improvement suggestions
+
+**Analytics (Optional):**
+- [Analytics Plan](./docs/analytics/ANALYTICS_MCP_PLAN.md) - Privacy-first analytics
+- [Analytics Security](./docs/analytics/MCP_ANALYTICS_SECURITY_GUIDE.md) - Security implementation guide
+- [Local Analytics](./docs/analytics/LOCAL_ANALYTICS_GUIDE.md) - Setup guide
+
+**Technical Documentation:**
+- [NOAA API Research](./docs/NOAA_API_RESEARCH.md) - NOAA API integration details
+- [Historical Data Plan](./docs/HISTORICAL_DATA_PLAN.md) - Historical weather implementation
+- [MCP Best Practices](./docs/MCP_BEST_PRACTICES.md) - MCP protocol guidelines
+
 ## License
 
 MIT

package/dist/analytics/anonymizer.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Data anonymization utilities for privacy-first analytics
+ * Ensures no PII is collected as per docs/ANALYTICS_MCP_PLAN.md
+ */
+import { AnalyticsEvent, AnalyticsLevel } from './types.js';
+/**
+ * Raw event data before anonymization
+ * Includes all possible fields that might be collected
+ */
+interface RawEventData {
+    version: string;
+    tool: string;
+    status: 'success' | 'error';
+    timestamp_hour: string;
+    analytics_level?: AnalyticsLevel;
+    error_type?: string;
+    response_time_ms?: number;
+    service?: string;
+    cache_hit?: boolean;
+    retry_count?: number;
+    country?: string;
+    parameters?: Record<string, unknown>;
+    session_id?: string;
+    sequence_number?: number;
+}
+/**
+ * Anonymize event data based on analytics level
+ * Strips sensitive information and ensures privacy compliance
+ */
+export declare function anonymizeEvent(rawData: RawEventData, level: AnalyticsLevel, salt?: string): AnalyticsEvent;
+/**
+ * Round timestamp to nearest hour for privacy
+ * Prevents precise user tracking
+ */
+export declare function roundToHour(date: Date): string;
+export {};
+//# sourceMappingURL=anonymizer.d.ts.map

package/dist/analytics/anonymizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anonymizer.d.ts","sourceRoot":"","sources":["../../src/analytics/anonymizer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5D;;;GAGG;AACH,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,cAAc,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,cAAc,EACrB,IAAI,CAAC,EAAE,MAAM,GACZ,cAAc,CA0ChB;AAiED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAI9C"}

package/dist/analytics/anonymizer.js

@@ -0,0 +1,112 @@
+/**
+ * Data anonymization utilities for privacy-first analytics
+ * Ensures no PII is collected as per docs/ANALYTICS_MCP_PLAN.md
+ */
+import crypto from 'crypto';
+/**
+ * Anonymize event data based on analytics level
+ * Strips sensitive information and ensures privacy compliance
+ */
+export function anonymizeEvent(rawData, level, salt) {
+    // Base event (minimal level) - always included
+    const baseEvent = {
+        version: rawData.version,
+        tool: rawData.tool,
+        status: rawData.status,
+        timestamp_hour: rawData.timestamp_hour,
+        analytics_level: 'minimal',
+        ...(rawData.status === 'error' && rawData.error_type ? { error_type: rawData.error_type } : {}),
+    };
+    // Return minimal level (no additional data)
+    if (level === 'minimal') {
+        return baseEvent;
+    }
+    // Standard level - add performance metrics
+    const standardEvent = {
+        ...baseEvent,
+        analytics_level: 'standard',
+        ...(rawData.response_time_ms !== undefined && { response_time_ms: rawData.response_time_ms }),
+        ...(rawData.service && { service: rawData.service }),
+        ...(rawData.cache_hit !== undefined && { cache_hit: rawData.cache_hit }),
+        ...(rawData.retry_count !== undefined && { retry_count: rawData.retry_count }),
+        ...(rawData.country && { country: rawData.country }),
+    };
+    // Return standard level
+    if (level === 'standard') {
+        return standardEvent;
+    }
+    // Detailed level - add anonymized workflow data
+    const detailedEvent = {
+        ...standardEvent,
+        analytics_level: 'detailed',
+        ...(rawData.parameters && { parameters: sanitizeParameters(rawData.parameters) }),
+        ...(rawData.session_id && { session_id: hashSessionId(rawData.session_id, salt) }),
+        ...(rawData.sequence_number !== undefined && { sequence_number: rawData.sequence_number }),
+    };
+    return detailedEvent;
+}
+/**
+ * Sanitize tool parameters - ONLY keep safe, non-identifying values
+ * NEVER include: coordinates, location names, user input
+ */
+function sanitizeParameters(params) {
+    const safe = {};
+    // Allowlist of safe parameters that don't contain PII
+    const allowedParams = [
+        'days',
+        'granularity',
+        'source',
+        'forecast_type',
+        'include_normals',
+        'include_fire_weather',
+        'include_severe_weather',
+        'active_only',
+        'limit',
+        'radius',
+        'units',
+        'hourly',
+        'daily',
+    ];
+    for (const key of allowedParams) {
+        if (params[key] !== undefined) {
+            // Only include primitive values (no objects/arrays that might contain PII)
+            const value = params[key];
+            if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                safe[key] = value;
+            }
+        }
+    }
+    // NEVER include these (blocklist for extra safety):
+    // - latitude, longitude, lat, lon
+    // - location, address, city, state, zip, postal_code
+    // - user, name, email, phone
+    // - any user-provided strings
+    return safe;
+}
+/**
+ * Create one-way hash of session ID
+ * Cannot be reversed to identify users
+ */
+function hashSessionId(sessionId, salt) {
+    // Salt should always be provided by config (auto-generated)
+    // Fallback to environment variable if somehow not provided
+    const sessionSalt = salt || process.env.ANALYTICS_SALT || '';
+    if (!sessionSalt) {
+        throw new Error('Analytics salt must be provided for session ID hashing');
+    }
+    return crypto
+        .createHash('sha256')
+        .update(sessionId + sessionSalt)
+        .digest('hex')
+        .substring(0, 16); // Shortened for storage efficiency
+}
+/**
+ * Round timestamp to nearest hour for privacy
+ * Prevents precise user tracking
+ */
+export function roundToHour(date) {
+    const rounded = new Date(date);
+    rounded.setMinutes(0, 0, 0);
+    return rounded.toISOString();
+}
+//# sourceMappingURL=anonymizer.js.map

package/dist/analytics/anonymizer.js.map

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

package/dist/analytics/collector.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Analytics event collector and batch manager
+ * Buffers events in memory and periodically flushes to analytics server
+ */
+import { AnalyticsConfig, ToolExecutionMetadata } from './types.js';
+/**
+ * AnalyticsCollector - Manages event buffering and batch sending
+ * Implements privacy-first analytics with automatic flushing
+ */
+export declare class AnalyticsCollector {
+    private buffer;
+    private config;
+    private flushTimer;
+    private sessionId;
+    private sequenceNumber;
+    private isShuttingDown;
+    private consecutiveFailures;
+    private circuitOpen;
+    private circuitOpenUntil;
+    private readonly MAX_CONSECUTIVE_FAILURES;
+    private readonly CIRCUIT_BREAKER_RESET_MS;
+    private errorCount;
+    private successCount;
+    private readonly ERROR_THRESHOLD;
+    private lastFlushTime;
+    private flushCount;
+    private readonly MIN_FLUSH_INTERVAL_MS;
+    private readonly MAX_FLUSHES_PER_HOUR;
+    private readonly MAX_EVENTS_PER_MINUTE;
+    private recentEventTimestamps;
+    private readonly MAX_BUFFER_SIZE;
+    private readonly FLUSH_INTERVAL_MS;
+    constructor(config: AnalyticsConfig);
+    /**
+     * Track a tool execution event
+     * Fails silently - analytics should never break the application
+     */
+    trackToolCall(tool: string, status: 'success' | 'error', metadata?: ToolExecutionMetadata): Promise<void>;
+    /**
+     * Flush buffered events to analytics server
+     * Called automatically on timer or when buffer is full
+     * Implements circuit breaker pattern (3.7)
+     */
+    flush(): Promise<void>;
+    /**
+     * Start periodic flush timer
+     */
+    private startFlushTimer;
+    /**
+     * Stop flush timer
+     */
+    private stopFlushTimer;
+    /**
+     * Generate unique session ID
+     * Used for tracking tool call sequences in detailed mode
+     */
+    private generateSessionId;
+    /**
+     * Public shutdown method called by main shutdown handler
+     * Ensures buffered events are sent before process exits
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get current buffer size (for testing)
+     */
+    getBufferSize(): number;
+    /**
+     * Get session ID (for testing)
+     */
+    getSessionId(): string;
+}
+//# sourceMappingURL=collector.d.ts.map

package/dist/analytics/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../src/analytics/collector.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAAE,eAAe,EAAkB,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEpF;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,cAAc,CAAS;IAG/B,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAK;IAC9C,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAiB;IAG1D,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAM;IAGtC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAS;IAC/C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAM;IAC3C,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAM;IAC5C,OAAO,CAAC,qBAAqB,CAAgB;IAE7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAO;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAiB;gBAEvC,MAAM,EAAE,eAAe;IAanC;;;OAGG;IACU,aAAa,CACxB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,GAAG,OAAO,EAC3B,QAAQ,GAAE,qBAA0B,GACnC,OAAO,CAAC,IAAI,CAAC;IA+GhB;;;;OAIG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA6EnC;;OAEG;IACH,OAAO,CAAC,eAAe;IAavB;;OAEG;IACH,OAAO,CAAC,cAAc;IAOtB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;OAGG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBtC;;OAEG;IACI,aAAa,IAAI,MAAM;IAI9B;;OAEG;IACI,YAAY,IAAI,MAAM;CAG9B"}