🌐 MetricTide Client

Real-Time Metric Reporting Made Effortless

A resilient, smart client designed to stream, store, and query metrics to and from a MetricTide analytics server. Whether you're tracking product usage, performance signals, or user behavior, MetricTide Client offers seamless integration, offline robustness, and predictive insights out of the box.

🚀 Features

• 📡 MetricTide Server Integration – Stream custom metrics to a MetricTide server in real time.
• 📦 Offline-First Buffering – Automatically stores unsent metrics and syncs them once connectivity is restored.
• 🧠 Device-Aware Identity – Assigns a consistent, device-specific metric identifier.
• 🔄 Auto Syncing – Periodically flushes stored metrics to the backend with retry logic.
• 🔍 Flexible Querying – Retrieve historical, real-time, and aggregate analytics.
• 🔐 Session-Based Communication – Securely transmit metrics through authenticated, session-aware channels.
• 🔧 Custom Gateways – Override transport logic with your own network layer.

⚙️ System Requirements

| Requirement | Version | |----------------|-----------------------------| | Browser | Chrome ≥ 91, Firefox ≥ 90 | | JavaScript | ES2020+ | | npm | ≥ 9.x (recommended) | | OS | Windows, macOS, Linux |

🛠️ Configuration

MetricTideClient Options

| Option | Type | Default | Description | |----------------------------|-------------|-------------|-------------| | connectionURL | string | "" | URL to check server availability. | | baseURL | string | "" | API base path for reporting and querying metrics. | | deviceIDPrefix | string | "MT-" | Prefix used for the generated metric device ID. | | flushInterval | number | 10000 | How often (in ms) to attempt syncing stored metrics. | | offlineFirst | boolean | false | Enables buffering and deferred syncing when offline. | | metricRequester | function | null | Optional custom request logic. | | metricGateway | function | fetch | Network method used for transport. | | metricLinkPairPath | string | "/metric-device/pair" | Endpoint for authenticating client device. | | metricLinkConfigurations | object | {} | Enables optional session-based communication. | | metricCacheConfigurations | object | {} | Storage configuration (name, version, store list, etc). | | metricStatusCheckerOptions| object | {} | Options for availability checking logic. |

📘 API Specifications

🎯 Tracking

| Method | Description | |--------|-------------| | track(domain, metric, options?) | Records a metric and attempts immediate or deferred transmission. | | sync() | Manually triggers an attempt to flush all stored metrics. | | activateOnlineListener() | Initiates the client's online event for metric syncing. | | activateSyncInterval() | Initiates metric flushing per flush interval. | | destroyOnlineListener() | Stops listening to the client's online event preventing metric syncing upon client connection. | | destroySyncInterval() | Stops metric flushing. | | destroy() | Stops syncing behavior and removes internal listeners. | | getDeviceID() | Returns the consistent, client-generated metric device ID. |

📄 Querying

| Method | Description | |--------|-------------| | getMetrics(filter) | Retrieves current metrics from the server. | | getMetricsSince(interval, source, filter) | Gets metrics from a time window (e.g., "5m", "1d"). | | getMetricsBetween(start, end, source, filter) | Retrieves metrics between two timestamps. | | getStoredMetrics(filter) | Loads metrics that were saved but not yet synced. | | getMetricsFromDomains(domains, options) | Queries multiple domains in a single request. | | getMetricsInDomain(domain, options) | Queries metrics within a specific domain. | | getMetricByID(id) | Retrieves a metric by its unique ID. | | updateMetric(id, updates) | Updates an existing metric. |

📊 Aggregation & Prediction

| Method | Description | |--------|-------------| | getAggregate(name) | Returns aggregate stats for a named metric. | | getAggregateByType(type) | Retrieves grouped aggregates by type. | | groupByTag(tagKey) | Groups metrics based on a tag. | | getTimeSeries(name, options) | Returns a time series view of a metric. | | predictMetric(name, config) | Generates a short-term forecast for a metric. |

🧹 Cleanup

| Method | Description | |--------|-------------| | clearMetricsInDomain(domain, options) | Removes all metrics associated with a given domain. | | clearAllMetrics() | Removes all metrics globally. |

🔐 Session Communication (Optional)

Enable secure, session-aware metric transport using the metricLinkConfigurations object:

const client = new MetricTideClient({
     baseURL : "https://metrics.example.com",
     metricLinkPairPath : "/devices/pair",
     metricLinkConfigurations : {
          enabled : true,
          options : {
               persistSessionKey : false,
               persistSessionID : false,
               headers : {
                    Authorization : "Bearer YOUR_TOKEN"
               }
          }
     }
});

📦 Installation

npm install @trap_stevo/metrictide-client

✨ Basic Usage

import HUDMetricTide from "@trap_stevo/metrictide-client";

const client = new HUDMetricTide({
     baseURL : "https://metrics.example.com",
     connectionURL : "https://metrics.example.com/ping",
     offlineFirst : true,
     flushInterval : 8000
});

client.track("page_view", {
     value : 1,
     metadata : { route : "/dashboard" },
     tags : ["navigation"]
});

🔁 Example: Buffered Tracking

await client.track("interaction", {
     value : 1,
     metadata : { type : "click" },
     tags : ["button", "ui"]
});

If offline mode is enabled, this metric will be held until syncing becomes possible.

📊 Example: Fetching Recent Activity

const recent = await client.getMetricsSince("10m");

console.log("Recent Metrics:", recent);

🔮 Example: Forecasting Engagement

const prediction = await client.predictMetric("engagement_score", {
     interval : "5m",
     range : "1h",
     stepsAhead : 3
});

console.log("Predicted Engagement:", prediction);

📌 Example: Clearing a Domain

await client.clearMetricsInDomain("video_player");

📡 Server Integration

Designed to interface seamlessly with MetricTide, enabling full tracking, querying, and forecasting.

📜 License

See LICENSE.md for details.