@egintegrations/telemetry 0.1.0

package/README.md

@@ -0,0 +1,132 @@
+# @egi/telemetry
+
+Official JavaScript/TypeScript telemetry SDK for EGIntegrations client engines.
+
+## Installation
+
+```bash
+# npm
+npm install @egi/telemetry
+
+# pnpm
+pnpm add @egi/telemetry
+
+# yarn
+yarn add @egi/telemetry
+```
+
+## Quick Start
+
+```typescript
+import { TelemetryClient } from '@egi/telemetry';
+
+// Initialize the client
+const telemetry = new TelemetryClient({
+  engineName: 'my-awesome-engine',
+  skuVersion: '1.0.0',
+  controlCenterUrl: 'https://control-center.egintegrations.com',
+  authToken: 'optional-auth-token', // Optional
+  enabled: true, // Default: true
+});
+
+// Register your engine
+await telemetry.register({
+  environment: 'production',
+  region: 'us-east-1',
+});
+
+// Report status
+await telemetry.reportStatus({
+  status: 'healthy',
+  metadata: {
+    activeConnections: 42,
+    queueSize: 100,
+  },
+  metrics: {
+    cpu_usage: 45.2,
+    memory_mb: 512,
+  },
+});
+
+// Send custom metrics
+await telemetry.sendMetrics({
+  metrics: {
+    orders_processed: 150,
+    revenue_usd: 5420.50,
+  },
+});
+```
+
+## Express/Fastify Integration
+
+```typescript
+import express from 'express';
+import { TelemetryClient } from '@egi/telemetry';
+
+const app = express();
+const telemetry = new TelemetryClient({
+  engineName: 'api-server',
+  skuVersion: '1.0.0',
+  controlCenterUrl: 'https://control-center.egintegrations.com',
+});
+
+// Automatic request metrics
+app.use(telemetry.middleware());
+
+app.listen(3000);
+```
+
+## Automatic Health Checks
+
+```typescript
+// Report health every 60 seconds
+const healthCheckTimer = telemetry.startHealthCheck(60000);
+
+// Stop health checks
+clearInterval(healthCheckTimer);
+```
+
+## Graceful Shutdown
+
+```typescript
+process.on('SIGTERM', async () => {
+  await telemetry.shutdown();
+  process.exit(0);
+});
+```
+
+## API Reference
+
+### `TelemetryClient`
+
+#### Constructor Options
+
+- `engineName` (string, required) - Unique name for your engine
+- `skuVersion` (string, required) - Version of your engine (e.g., "1.0.0")
+- `controlCenterUrl` (string, required) - URL of your control center
+- `authToken` (string, optional) - Authentication token if required
+- `enabled` (boolean, optional) - Enable/disable telemetry (default: true)
+
+#### Methods
+
+##### `register(metadata?: object): Promise<void>`
+Register your engine with the control center.
+
+##### `reportStatus(payload: StatusPayload): Promise<void>`
+Report engine status. Status can be: 'healthy', 'degraded', 'unhealthy', 'starting', 'stopping'.
+
+##### `sendMetrics(payload: MetricsPayload): Promise<void>`
+Send custom metrics to the control center.
+
+##### `startHealthCheck(intervalMs?: number): NodeJS.Timeout`
+Start automatic health checks (default: every 60 seconds).
+
+##### `middleware(): Function`
+Express/Fastify middleware for automatic request tracking.
+
+##### `shutdown(): Promise<void>`
+Report graceful shutdown to control center.
+
+## License
+
+Proprietary - EGIntegrations

package/dist/index.d.mts

@@ -0,0 +1,49 @@
+interface TelemetryConfig {
+    engineName: string;
+    skuVersion: string;
+    controlCenterUrl: string;
+    authToken?: string;
+    enabled?: boolean;
+}
+interface StatusPayload {
+    status: 'healthy' | 'degraded' | 'unhealthy' | 'starting' | 'stopping';
+    metadata?: Record<string, any>;
+    metrics?: Record<string, number>;
+    message?: string;
+}
+interface MetricsPayload {
+    metrics: Record<string, number>;
+    timestamp?: string;
+}
+declare class TelemetryClient {
+    private config;
+    private client;
+    private engineId?;
+    constructor(config: TelemetryConfig);
+    /**
+     * Register the engine with the control center
+     */
+    register(metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Report engine status to the control center
+     */
+    reportStatus(payload: StatusPayload): Promise<void>;
+    /**
+     * Send metrics to the control center
+     */
+    sendMetrics(payload: MetricsPayload): Promise<void>;
+    /**
+     * Start periodic health checks (reports status every interval)
+     */
+    startHealthCheck(intervalMs?: number): NodeJS.Timeout;
+    /**
+     * Create Express/Fastify middleware for automatic telemetry
+     */
+    middleware(): (req: any, res: any, next: any) => Promise<void>;
+    /**
+     * Graceful shutdown - report stopping status
+     */
+    shutdown(): Promise<void>;
+}
+
+export { type MetricsPayload, type StatusPayload, TelemetryClient, type TelemetryConfig, TelemetryClient as default };

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+interface TelemetryConfig {
+    engineName: string;
+    skuVersion: string;
+    controlCenterUrl: string;
+    authToken?: string;
+    enabled?: boolean;
+}
+interface StatusPayload {
+    status: 'healthy' | 'degraded' | 'unhealthy' | 'starting' | 'stopping';
+    metadata?: Record<string, any>;
+    metrics?: Record<string, number>;
+    message?: string;
+}
+interface MetricsPayload {
+    metrics: Record<string, number>;
+    timestamp?: string;
+}
+declare class TelemetryClient {
+    private config;
+    private client;
+    private engineId?;
+    constructor(config: TelemetryConfig);
+    /**
+     * Register the engine with the control center
+     */
+    register(metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Report engine status to the control center
+     */
+    reportStatus(payload: StatusPayload): Promise<void>;
+    /**
+     * Send metrics to the control center
+     */
+    sendMetrics(payload: MetricsPayload): Promise<void>;
+    /**
+     * Start periodic health checks (reports status every interval)
+     */
+    startHealthCheck(intervalMs?: number): NodeJS.Timeout;
+    /**
+     * Create Express/Fastify middleware for automatic telemetry
+     */
+    middleware(): (req: any, res: any, next: any) => Promise<void>;
+    /**
+     * Graceful shutdown - report stopping status
+     */
+    shutdown(): Promise<void>;
+}
+
+export { type MetricsPayload, type StatusPayload, TelemetryClient, type TelemetryConfig, TelemetryClient as default };

package/dist/index.js

@@ -0,0 +1,152 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  TelemetryClient: () => TelemetryClient,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var import_axios = __toESM(require("axios"));
+var TelemetryClient = class {
+  constructor(config) {
+    this.config = {
+      ...config,
+      enabled: config.enabled ?? true
+    };
+    this.client = import_axios.default.create({
+      baseURL: this.config.controlCenterUrl,
+      timeout: 5e3,
+      headers: {
+        "Content-Type": "application/json",
+        ...this.config.authToken && { Authorization: `Bearer ${this.config.authToken}` }
+      }
+    });
+  }
+  /**
+   * Register the engine with the control center
+   */
+  async register(metadata) {
+    if (!this.config.enabled) return;
+    try {
+      const response = await this.client.post("/api/telemetry/register", {
+        engine_name: this.config.engineName,
+        sku_version: this.config.skuVersion,
+        metadata: metadata || {}
+      });
+      this.engineId = response.data.engine_id;
+      console.log(`[EGI Telemetry] Registered engine: ${this.config.engineName} (${this.engineId})`);
+    } catch (error) {
+      console.error("[EGI Telemetry] Failed to register:", error);
+      throw error;
+    }
+  }
+  /**
+   * Report engine status to the control center
+   */
+  async reportStatus(payload) {
+    if (!this.config.enabled) return;
+    try {
+      await this.client.post("/api/telemetry/status", {
+        engine_name: this.config.engineName,
+        sku_version: this.config.skuVersion,
+        status: payload.status,
+        metadata: payload.metadata || {},
+        metrics: payload.metrics || {},
+        message: payload.message,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } catch (error) {
+      console.error("[EGI Telemetry] Failed to report status:", error);
+    }
+  }
+  /**
+   * Send metrics to the control center
+   */
+  async sendMetrics(payload) {
+    if (!this.config.enabled) return;
+    try {
+      await this.client.post("/api/telemetry/metrics", {
+        engine_name: this.config.engineName,
+        sku_version: this.config.skuVersion,
+        metrics: payload.metrics,
+        timestamp: payload.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } catch (error) {
+      console.error("[EGI Telemetry] Failed to send metrics:", error);
+    }
+  }
+  /**
+   * Start periodic health checks (reports status every interval)
+   */
+  startHealthCheck(intervalMs = 6e4) {
+    return setInterval(async () => {
+      await this.reportStatus({
+        status: "healthy",
+        metadata: {
+          uptime: process.uptime(),
+          memory: process.memoryUsage()
+        }
+      });
+    }, intervalMs);
+  }
+  /**
+   * Create Express/Fastify middleware for automatic telemetry
+   */
+  middleware() {
+    return async (req, res, next) => {
+      const start = Date.now();
+      res.on("finish", async () => {
+        const duration = Date.now() - start;
+        await this.sendMetrics({
+          metrics: {
+            request_duration_ms: duration,
+            status_code: res.statusCode
+          }
+        });
+      });
+      next();
+    };
+  }
+  /**
+   * Graceful shutdown - report stopping status
+   */
+  async shutdown() {
+    await this.reportStatus({
+      status: "stopping",
+      message: "Engine shutting down"
+    });
+  }
+};
+var index_default = TelemetryClient;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TelemetryClient
+});

package/dist/index.mjs

@@ -0,0 +1,117 @@
+// src/index.ts
+import axios from "axios";
+var TelemetryClient = class {
+  constructor(config) {
+    this.config = {
+      ...config,
+      enabled: config.enabled ?? true
+    };
+    this.client = axios.create({
+      baseURL: this.config.controlCenterUrl,
+      timeout: 5e3,
+      headers: {
+        "Content-Type": "application/json",
+        ...this.config.authToken && { Authorization: `Bearer ${this.config.authToken}` }
+      }
+    });
+  }
+  /**
+   * Register the engine with the control center
+   */
+  async register(metadata) {
+    if (!this.config.enabled) return;
+    try {
+      const response = await this.client.post("/api/telemetry/register", {
+        engine_name: this.config.engineName,
+        sku_version: this.config.skuVersion,
+        metadata: metadata || {}
+      });
+      this.engineId = response.data.engine_id;
+      console.log(`[EGI Telemetry] Registered engine: ${this.config.engineName} (${this.engineId})`);
+    } catch (error) {
+      console.error("[EGI Telemetry] Failed to register:", error);
+      throw error;
+    }
+  }
+  /**
+   * Report engine status to the control center
+   */
+  async reportStatus(payload) {
+    if (!this.config.enabled) return;
+    try {
+      await this.client.post("/api/telemetry/status", {
+        engine_name: this.config.engineName,
+        sku_version: this.config.skuVersion,
+        status: payload.status,
+        metadata: payload.metadata || {},
+        metrics: payload.metrics || {},
+        message: payload.message,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } catch (error) {
+      console.error("[EGI Telemetry] Failed to report status:", error);
+    }
+  }
+  /**
+   * Send metrics to the control center
+   */
+  async sendMetrics(payload) {
+    if (!this.config.enabled) return;
+    try {
+      await this.client.post("/api/telemetry/metrics", {
+        engine_name: this.config.engineName,
+        sku_version: this.config.skuVersion,
+        metrics: payload.metrics,
+        timestamp: payload.timestamp || (/* @__PURE__ */ new Date()).toISOString()
+      });
+    } catch (error) {
+      console.error("[EGI Telemetry] Failed to send metrics:", error);
+    }
+  }
+  /**
+   * Start periodic health checks (reports status every interval)
+   */
+  startHealthCheck(intervalMs = 6e4) {
+    return setInterval(async () => {
+      await this.reportStatus({
+        status: "healthy",
+        metadata: {
+          uptime: process.uptime(),
+          memory: process.memoryUsage()
+        }
+      });
+    }, intervalMs);
+  }
+  /**
+   * Create Express/Fastify middleware for automatic telemetry
+   */
+  middleware() {
+    return async (req, res, next) => {
+      const start = Date.now();
+      res.on("finish", async () => {
+        const duration = Date.now() - start;
+        await this.sendMetrics({
+          metrics: {
+            request_duration_ms: duration,
+            status_code: res.statusCode
+          }
+        });
+      });
+      next();
+    };
+  }
+  /**
+   * Graceful shutdown - report stopping status
+   */
+  async shutdown() {
+    await this.reportStatus({
+      status: "stopping",
+      message: "Engine shutting down"
+    });
+  }
+};
+var index_default = TelemetryClient;
+export {
+  TelemetryClient,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@egintegrations/telemetry",
+  "version": "0.1.0",
+  "description": "Telemetry SDK for EGIntegrations client engines",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"No tests yet\""
+  },
+  "keywords": [
+    "telemetry",
+    "monitoring",
+    "egi",
+    "metrics"
+  ],
+  "author": "EGIntegrations",
+  "license": "PROPRIETARY",
+  "dependencies": {
+    "axios": "^1.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}