@egintegrations/telemetry 0.1.0 → 0.2.0

package/README.md

@@ -1,4 +1,4 @@
-# @egi/telemetry
+# @egintegrations/telemetry
 
 Official JavaScript/TypeScript telemetry SDK for EGIntegrations client engines.
 
@@ -6,19 +6,132 @@ Official JavaScript/TypeScript telemetry SDK for EGIntegrations client engines.
 
 ```bash
 # npm
-npm install @egi/telemetry
+npm install @egintegrations/telemetry
 
 # pnpm
-pnpm add @egi/telemetry
+pnpm add @egintegrations/telemetry
 
 # yarn
-yarn add @egi/telemetry
+yarn add @egintegrations/telemetry
 ```
 
-## Quick Start
+## Quick Setup with CLI
+
+The fastest way to integrate telemetry into your project:
+
+### Interactive Setup
+
+```bash
+npx @egintegrations/telemetry init
+```
+
+The CLI will:
+1. Detect your framework (Next.js, Express, Fastify, or generic)
+2. Prompt for engine name, SKU version, and Control Center URL
+3. Generate configuration file (`.egi/telemetry.json`)
+4. Create integration code (`lib/telemetry.ts` for Next.js, `src/telemetry.ts` for Express)
+5. Add environment variables (`.env.local` or `.env`)
+6. Optionally generate status endpoint boilerplate
+
+### Non-Interactive Setup
+
+For CI/CD or automated setups:
+
+```bash
+npx @egintegrations/telemetry init \
+  --engine my-engine \
+  --sku 1.0.0 \
+  --url https://control-center.egintegrations.com \
+  --token your-auth-token
+```
+
+### CLI Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--engine <name>` | Engine name (required) | - |
+| `--sku <version>` | SKU version (required) | - |
+| `--url <url>` | Control Center URL (required) | - |
+| `--token <token>` | Auth token (optional) | - |
+| `--modules <modules>` | Comma-separated module list | - |
+| `--output <path>` | Config file location | `.egi/telemetry.json` |
+| `--framework <type>` | Force framework type (nextjs, express, fastify, generic) | Auto-detected |
+| `--no-interactive` | Skip prompts, fail on missing args | Interactive mode |
+| `--no-codegen` | Only generate config file | Code generation enabled |
+| `--status-endpoint` | Generate status endpoint boilerplate | false |
+
+### Framework-Specific Examples
+
+#### Next.js Project
+
+```bash
+cd my-nextjs-app
+npx @egintegrations/telemetry init
+```
+
+**Generated Files:**
+- `.egi/telemetry.json` - Configuration
+- `lib/telemetry.ts` - Telemetry client singleton
+- `.env.local` - Environment variables
+- `app/api/engine-status/route.ts` - Status endpoint (if requested)
+
+**Usage in Next.js:**
+```typescript
+// app/api/data/route.ts
+import telemetry from '@/lib/telemetry';
+
+export async function GET() {
+  await telemetry.sendMetrics({
+    metrics: { api_calls: 1 }
+  });
+
+  return Response.json({ ok: true });
+}
+```
+
+#### Express Project
+
+```bash
+cd my-express-app
+npx @egintegrations/telemetry init
+```
+
+**Generated Files:**
+- `.egi/telemetry.json` - Configuration
+- `src/telemetry.ts` - Telemetry client
+- `.env` - Environment variables
+- `src/routes/status.ts` - Status endpoint (if requested)
+
+**Usage in Express:**
+```typescript
+// src/index.ts
+import express from 'express';
+import telemetry from './telemetry';
+
+const app = express();
+
+// Auto-track requests
+app.use(telemetry.middleware());
+
+// Use in routes
+app.get('/data', async (req, res) => {
+  await telemetry.sendMetrics({ metrics: { requests: 1 } });
+  res.json({ ok: true });
+});
+
+app.listen(3000, async () => {
+  await telemetry.register();
+});
+```
+
+## Manual Setup (Advanced)
+
+If you prefer manual setup instead of using the CLI:
+
+### Quick Start
 
 ```typescript
-import { TelemetryClient } from '@egi/telemetry';
+import { TelemetryClient } from '@egintegrations/telemetry';
 
 // Initialize the client
 const telemetry = new TelemetryClient({
@@ -57,11 +170,11 @@ await telemetry.sendMetrics({
 });
 ```
 
-## Express/Fastify Integration
+### Express/Fastify Integration
 
 ```typescript
 import express from 'express';
-import { TelemetryClient } from '@egi/telemetry';
+import { TelemetryClient } from '@egintegrations/telemetry';
 
 const app = express();
 const telemetry = new TelemetryClient({
@@ -76,7 +189,7 @@ app.use(telemetry.middleware());
 app.listen(3000);
 ```
 
-## Automatic Health Checks
+### Automatic Health Checks
 
 ```typescript
 // Report health every 60 seconds
@@ -86,7 +199,7 @@ const healthCheckTimer = telemetry.startHealthCheck(60000);
 clearInterval(healthCheckTimer);
 ```
 
-## Graceful Shutdown
+### Graceful Shutdown
 
 ```typescript
 process.on('SIGTERM', async () => {

package/dist/cli.js

@@ -0,0 +1,503 @@
+#!/usr/bin/env node
+"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 __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
+));
+
+// src/cli.ts
+var import_commander = require("commander");
+
+// src/cli/detector.ts
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+async function detectFramework(cwd) {
+  const pkgJsonPath = path.join(cwd, "package.json");
+  if (!fs.existsSync(pkgJsonPath)) {
+    return { type: "generic", rootDir: cwd };
+  }
+  try {
+    const pkgContent = fs.readFileSync(pkgJsonPath, "utf-8");
+    const pkg = JSON.parse(pkgContent);
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps.next) {
+      const hasAppDir = fs.existsSync(path.join(cwd, "app"));
+      return {
+        type: "nextjs",
+        version: deps.next,
+        appDir: hasAppDir,
+        rootDir: cwd
+      };
+    }
+    if (deps.express) {
+      return {
+        type: "express",
+        version: deps.express,
+        rootDir: cwd
+      };
+    }
+    if (deps.fastify) {
+      return {
+        type: "fastify",
+        version: deps.fastify,
+        rootDir: cwd
+      };
+    }
+    return { type: "generic", rootDir: cwd };
+  } catch (error) {
+    console.warn("Failed to parse package.json, assuming generic project");
+    return { type: "generic", rootDir: cwd };
+  }
+}
+
+// src/cli/prompts.ts
+var import_prompts2 = __toESM(require("prompts"));
+
+// src/cli/utils.ts
+var fs2 = __toESM(require("fs"));
+var path2 = __toESM(require("path"));
+var import_prompts = __toESM(require("prompts"));
+async function writeFile(file) {
+  const dir = path2.dirname(file.path);
+  await fs2.promises.mkdir(dir, { recursive: true });
+  if (fs2.existsSync(file.path) && file.overwrite !== true) {
+    const { confirm } = await (0, import_prompts.default)({
+      type: "confirm",
+      name: "confirm",
+      message: `File ${file.path} already exists. Overwrite?`,
+      initial: false
+    });
+    if (!confirm) {
+      console.log(`\u23ED\uFE0F  Skipped: ${file.path}`);
+      return;
+    }
+  }
+  if (file.path.endsWith(".env") || file.path.endsWith(".env.local")) {
+    await appendEnvFile(file.path, file.content);
+  } else {
+    await fs2.promises.writeFile(file.path, file.content, "utf-8");
+    console.log(`\u2713 Created: ${file.path}`);
+  }
+}
+async function appendEnvFile(envPath, content) {
+  let existing = "";
+  if (fs2.existsSync(envPath)) {
+    existing = await fs2.promises.readFile(envPath, "utf-8");
+  }
+  if (existing.includes("EGI_ENGINE_NAME")) {
+    console.log(`\u26A0\uFE0F  ${envPath} already contains EGI variables, skipping`);
+    return;
+  }
+  const separator = existing.trim() ? "\n\n" : "";
+  const updated = existing + separator + content;
+  await fs2.promises.writeFile(envPath, updated, "utf-8");
+  console.log(`\u2713 Updated: ${envPath}`);
+}
+function validateSku(sku) {
+  return /^\d+\.\d+\.\d+/.test(sku);
+}
+
+// src/cli/prompts.ts
+async function gatherOptions(cliArgs, detected) {
+  const questions = [];
+  if (!cliArgs.engine) {
+    questions.push({
+      type: "text",
+      name: "engine",
+      message: "Engine name (e.g., hs-and-c):",
+      validate: (v) => v.length > 0 || "Engine name is required"
+    });
+  }
+  if (!cliArgs.sku) {
+    questions.push({
+      type: "text",
+      name: "sku",
+      message: "SKU version (e.g., 1.0.0):",
+      validate: (v) => validateSku(v) || "Invalid SKU format (expected: X.Y.Z...)"
+    });
+  }
+  if (!cliArgs.url) {
+    questions.push({
+      type: "text",
+      name: "url",
+      message: "Control Center URL:",
+      initial: "https://control-center.egintegrations.com"
+    });
+  }
+  if (cliArgs.token === void 0) {
+    questions.push({
+      type: "password",
+      name: "token",
+      message: "Auth token (optional, press Enter to skip):"
+    });
+  }
+  if (!cliArgs.framework) {
+    const frameworkChoices = [
+      { title: `${detected.type} (detected)`, value: detected.type },
+      { title: "Next.js", value: "nextjs", disabled: detected.type === "nextjs" },
+      { title: "Express", value: "express", disabled: detected.type === "express" },
+      { title: "Fastify", value: "fastify", disabled: detected.type === "fastify" },
+      { title: "Generic/Other", value: "generic", disabled: detected.type === "generic" }
+    ].filter((choice) => !choice.disabled);
+    if (frameworkChoices.length > 1) {
+      questions.push({
+        type: "select",
+        name: "framework",
+        message: "Select framework:",
+        choices: frameworkChoices,
+        initial: 0
+      });
+    }
+  }
+  if (cliArgs.codegen !== false && detected.type !== "generic") {
+    questions.push({
+      type: "confirm",
+      name: "statusEndpoint",
+      message: "Generate status endpoint boilerplate?",
+      initial: true
+    });
+  }
+  const answers = await (0, import_prompts2.default)(questions, {
+    onCancel: () => {
+      console.log("\n\u274C Setup cancelled");
+      process.exit(0);
+    }
+  });
+  return {
+    engine: cliArgs.engine || answers.engine,
+    sku: cliArgs.sku || answers.sku,
+    url: cliArgs.url || answers.url,
+    token: cliArgs.token || answers.token || void 0,
+    modules: cliArgs.modules,
+    output: cliArgs.output || ".egi/telemetry.json",
+    framework: cliArgs.framework || answers.framework || detected.type,
+    codegen: cliArgs.codegen !== false,
+    statusEndpoint: cliArgs.statusEndpoint || answers.statusEndpoint || false
+  };
+}
+
+// src/cli/generators/nextjs.ts
+var path3 = __toESM(require("path"));
+
+// src/cli/generators/templates.ts
+function generateConfigFile(ctx) {
+  return JSON.stringify({
+    engine: ctx.engine,
+    sku: ctx.sku,
+    url: ctx.url,
+    ...ctx.token && { token: ctx.token },
+    ...ctx.modules && { modules: ctx.modules }
+  }, null, 2);
+}
+function generateNextjsTelemetryClient(ctx) {
+  return `import { TelemetryClient } from '@egintegrations/telemetry';
+
+const telemetry = new TelemetryClient({
+  engineName: process.env.EGI_ENGINE_NAME || '${ctx.engine}',
+  skuVersion: process.env.EGI_SKU_VERSION || '${ctx.sku}',
+  controlCenterUrl: process.env.EGI_CONTROL_CENTER_URL || '${ctx.url}',
+  ${ctx.token ? `authToken: process.env.EGI_AUTH_TOKEN,` : "// authToken: process.env.EGI_AUTH_TOKEN,  // Optional"}
+  enabled: process.env.NODE_ENV === 'production'
+});
+
+// Auto-register on first import in production
+if (process.env.NODE_ENV === 'production') {
+  telemetry.register().catch(err => {
+    console.error('[EGI Telemetry] Failed to register:', err);
+  });
+}
+
+export default telemetry;
+`;
+}
+function generateNextjsStatusEndpoint() {
+  return `import { NextResponse } from 'next/server';
+import telemetry from '@/lib/telemetry';
+
+export async function GET() {
+  try {
+    await telemetry.reportStatus({
+      status: 'healthy',
+      metadata: {
+        timestamp: new Date().toISOString(),
+        uptime: process.uptime()
+      },
+      metrics: {},
+      message: 'Engine is healthy'
+    });
+
+    return NextResponse.json({
+      status: 'ok',
+      timestamp: new Date().toISOString()
+    });
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    return NextResponse.json(
+      { status: 'error', message: errorMessage },
+      { status: 500 }
+    );
+  }
+}
+`;
+}
+function generateExpressTelemetryClient(ctx) {
+  return `import { TelemetryClient } from '@egintegrations/telemetry';
+
+const telemetry = new TelemetryClient({
+  engineName: process.env.EGI_ENGINE_NAME || '${ctx.engine}',
+  skuVersion: process.env.EGI_SKU_VERSION || '${ctx.sku}',
+  controlCenterUrl: process.env.EGI_CONTROL_CENTER_URL || '${ctx.url}',
+  ${ctx.token ? `authToken: process.env.EGI_AUTH_TOKEN,` : "// authToken: process.env.EGI_AUTH_TOKEN,  // Optional"}
+  enabled: process.env.NODE_ENV === 'production'
+});
+
+export default telemetry;
+`;
+}
+function generateExpressStatusRoute() {
+  return `import express from 'express';
+import telemetry from '../telemetry';
+
+const router = express.Router();
+
+router.get('/engine-status', async (req, res) => {
+  try {
+    await telemetry.reportStatus({
+      status: 'healthy',
+      metadata: {
+        uptime: process.uptime(),
+        memory: process.memoryUsage()
+      },
+      metrics: {},
+      message: 'Engine is healthy'
+    });
+
+    res.json({
+      status: 'ok',
+      timestamp: new Date().toISOString()
+    });
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    res.status(500).json({
+      status: 'error',
+      message: errorMessage
+    });
+  }
+});
+
+export default router;
+`;
+}
+function generateEnvVars(ctx) {
+  const lines = [
+    "# EGI Telemetry Configuration",
+    `EGI_ENGINE_NAME=${ctx.engine}`,
+    `EGI_SKU_VERSION=${ctx.sku}`,
+    `EGI_CONTROL_CENTER_URL=${ctx.url}`
+  ];
+  if (ctx.token) {
+    lines.push(`EGI_AUTH_TOKEN=${ctx.token}`);
+  }
+  return lines.join("\n");
+}
+
+// src/cli/generators/nextjs.ts
+var nextjsGenerator = {
+  name: "Next.js",
+  supports: (ctx) => ctx.framework.type === "nextjs",
+  async generate(ctx) {
+    const files = [];
+    files.push({
+      path: path3.join(ctx.rootDir, ctx.options.output),
+      content: generateConfigFile(ctx.options)
+    });
+    if (ctx.options.codegen) {
+      const libDir = path3.join(ctx.rootDir, "lib");
+      files.push({
+        path: path3.join(libDir, "telemetry.ts"),
+        content: generateNextjsTelemetryClient(ctx.options),
+        overwrite: false
+        // Ask if exists
+      });
+      if (ctx.framework.appDir && ctx.options.statusEndpoint) {
+        files.push({
+          path: path3.join(ctx.rootDir, "app/api/engine-status/route.ts"),
+          content: generateNextjsStatusEndpoint(),
+          overwrite: false
+        });
+      }
+      files.push({
+        path: path3.join(ctx.rootDir, ".env.local"),
+        content: generateEnvVars(ctx.options),
+        overwrite: false
+        // Append, don't replace
+      });
+    }
+    return files;
+  }
+};
+
+// src/cli/generators/express.ts
+var path4 = __toESM(require("path"));
+var fs3 = __toESM(require("fs"));
+var expressGenerator = {
+  name: "Express",
+  supports: (ctx) => ctx.framework.type === "express" || ctx.framework.type === "fastify",
+  async generate(ctx) {
+    const files = [];
+    files.push({
+      path: path4.join(ctx.rootDir, ctx.options.output),
+      content: generateConfigFile(ctx.options)
+    });
+    if (ctx.options.codegen) {
+      const hasSrcDir = fs3.existsSync(path4.join(ctx.rootDir, "src"));
+      const baseDir = hasSrcDir ? "src" : ".";
+      files.push({
+        path: path4.join(ctx.rootDir, baseDir, "telemetry.ts"),
+        content: generateExpressTelemetryClient(ctx.options),
+        overwrite: false
+      });
+      if (ctx.options.statusEndpoint) {
+        const routesDir = path4.join(ctx.rootDir, baseDir, "routes");
+        files.push({
+          path: path4.join(routesDir, "status.ts"),
+          content: generateExpressStatusRoute(),
+          overwrite: false
+        });
+      }
+      files.push({
+        path: path4.join(ctx.rootDir, ".env"),
+        content: generateEnvVars(ctx.options),
+        overwrite: false
+      });
+    }
+    return files;
+  }
+};
+
+// src/cli/generators/generic.ts
+var path5 = __toESM(require("path"));
+var genericGenerator = {
+  name: "Generic Node.js",
+  supports: () => true,
+  // Fallback generator, always supports
+  async generate(ctx) {
+    const files = [];
+    files.push({
+      path: path5.join(ctx.rootDir, ctx.options.output),
+      content: generateConfigFile(ctx.options)
+    });
+    console.log(`
+\u26A0\uFE0F  Generic project detected - only config file generated.
+
+To use the telemetry SDK, manually:
+1. Import the SDK: import { TelemetryClient } from '@egintegrations/telemetry';
+2. Create a client with your config
+3. Call telemetry.register() on startup
+
+Example:
+  import { TelemetryClient } from '@egintegrations/telemetry';
+
+  const telemetry = new TelemetryClient({
+    engineName: '${ctx.options.engine}',
+    skuVersion: '${ctx.options.sku}',
+    controlCenterUrl: '${ctx.options.url}',
+    ${ctx.options.token ? `authToken: '${ctx.options.token}',` : ""}
+    enabled: true
+  });
+
+  await telemetry.register();
+
+See README for full documentation.
+    `);
+    return files;
+  }
+};
+
+// src/cli/generators/index.ts
+var generators = [
+  nextjsGenerator,
+  expressGenerator,
+  genericGenerator
+  // Always last as fallback
+];
+async function runGenerator(ctx) {
+  const generator = generators.find((g) => g.supports(ctx));
+  if (!generator) {
+    throw new Error(`No generator found for framework: ${ctx.framework.type}`);
+  }
+  console.log(`
+\u{1F3A8} Using ${generator.name} generator
+`);
+  return generator.generate(ctx);
+}
+
+// src/cli/commands.ts
+async function initCommand(options) {
+  console.log("\u{1F680} EGI Telemetry SDK Initialization\n");
+  try {
+    const cwd = process.cwd();
+    console.log("\u{1F50D} Detecting framework...");
+    const detected = await detectFramework(cwd);
+    console.log(`   Found: ${detected.type}${detected.version ? ` v${detected.version}` : ""}`);
+    if (detected.type === "nextjs" && detected.appDir) {
+      console.log("   Next.js App Router detected");
+    }
+    console.log("");
+    const telemetryOptions = await gatherOptions(options, detected);
+    console.log("");
+    const ctx = {
+      options: telemetryOptions,
+      framework: detected,
+      rootDir: cwd
+    };
+    const files = await runGenerator(ctx);
+    for (const file of files) {
+      await writeFile(file);
+    }
+    console.log("\n\u2705 Telemetry SDK initialized successfully!\n");
+    if (telemetryOptions.codegen && detected.type !== "generic") {
+      console.log("\u{1F4DD} Next steps:");
+      console.log("   1. Review the generated files");
+      console.log("   2. Import telemetry in your code:");
+      if (detected.type === "nextjs") {
+        console.log("      import telemetry from '@/lib/telemetry';");
+      } else {
+        console.log("      import telemetry from './telemetry';");
+      }
+      console.log("   3. Start using telemetry.sendMetrics() in your app");
+      console.log("");
+    }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error("\n\u274C Error:", error.message);
+    } else {
+      console.error("\n\u274C Unknown error occurred");
+    }
+    process.exit(1);
+  }
+}
+
+// src/cli.ts
+var program = new import_commander.Command();
+program.name("egi-telemetry").description("EGIntegrations Telemetry SDK CLI").version("0.2.0");
+program.command("init").description("Initialize telemetry in your project").option("--engine <name>", "Engine name").option("--sku <version>", "SKU version").option("--url <url>", "Control Center URL").option("--token <token>", "Auth token (optional)").option("--modules <modules>", "Comma-separated module list").option("--output <path>", "Config output path", ".egi/telemetry.json").option("--framework <type>", "Framework (nextjs, express, fastify, generic)").option("--no-interactive", "Skip prompts, fail if args missing").option("--no-codegen", "Only generate config, skip integration code").option("--status-endpoint", "Generate status endpoint boilerplate").action(initCommand);
+program.parse();

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@egintegrations/telemetry",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Telemetry SDK for EGIntegrations client engines",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "bin": {
+    "egi-telemetry": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "require": "./dist/index.js",
@@ -13,9 +16,12 @@
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "build": "npm run build:lib && npm run build:cli",
+    "build:lib": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "build:cli": "tsup src/cli.ts --format cjs --no-dts --shims",
     "prepublishOnly": "npm run build",
-    "test": "echo \"No tests yet\""
+    "test": "echo \"No tests yet\"",
+    "dev:cli": "tsx src/cli.ts"
   },
   "keywords": [
     "telemetry",
@@ -26,11 +32,15 @@
   "author": "EGIntegrations",
   "license": "PROPRIETARY",
   "dependencies": {
-    "axios": "^1.6.0"
+    "axios": "^1.6.0",
+    "commander": "^12.0.0",
+    "prompts": "^2.4.2"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/prompts": "^2.4.9",
     "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
     "typescript": "^5.3.0"
   },
   "files": [