@trap_stevo/metrictide-client/README.md

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 robustne

# 🌐 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:

```js
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

```bash
npm install @trap_stevo/metrictide-client
```

---


## ✨ Basic Usage

```js
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

```js
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

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

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

---


## 🔮 Example: Forecasting Engagement

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

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

---


## 📌 Example: Clearing a Domain

```js
await client.clearMetricsInDomain("video_player");
```

---


## 📡 Server Integration

Designed to interface seamlessly with [MetricTide](https://www.npmjs.com/package/@trap_stevo/metrictide), enabling full tracking, querying, and forecasting.

---


## 📜 License

See [LICENSE.md](./LICENSE.md) for details.