@modern-admin/telemetry 0.1.0

package/dist/collect.d.ts

@@ -0,0 +1,17 @@
+import type { ModernAdmin } from '@modern-admin/core';
+import type { TelemetryInfo } from './types.js';
+/**
+ * Build a `TelemetryInfo` snapshot from a running `ModernAdmin` instance.
+ * Reads only technical/aggregate data — no resource names, record
+ * contents, user data, or secrets are captured.
+ *
+ * This function is pure (no network I/O). Pass the result to
+ * `reportTelemetry` to ship it.
+ */
+export declare function collectTelemetryInfo(admin: ModernAdmin): TelemetryInfo;
+/**
+ * Reset the per-process instance ID (test helper only).
+ * @internal
+ */
+export declare function _resetInstanceId(): void;
+//# sourceMappingURL=collect.d.ts.map

package/dist/collect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.d.ts","sourceRoot":"","sources":["../src/collect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAK/C;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAuCtE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

package/dist/collect.js

@@ -0,0 +1,58 @@
+import { uuidv7 } from '@modern-admin/core';
+/** Stable per-process identifier (not persisted). */
+let _instanceId;
+/**
+ * Build a `TelemetryInfo` snapshot from a running `ModernAdmin` instance.
+ * Reads only technical/aggregate data — no resource names, record
+ * contents, user data, or secrets are captured.
+ *
+ * This function is pure (no network I/O). Pass the result to
+ * `reportTelemetry` to ship it.
+ */
+export function collectTelemetryInfo(admin) {
+    if (!_instanceId)
+        _instanceId = uuidv7();
+    // Derive a short adapter name from the Database constructor class name.
+    // Examples: "PrismaDatabase" → "prisma", "DrizzleDatabase" → "drizzle",
+    // anything else → "unknown".
+    const adapters = (admin.options.adapters ?? []).map((a) => {
+        const raw = a.Database.name ?? '';
+        const lower = raw.toLowerCase();
+        if (lower.includes('prisma'))
+            return 'prisma';
+        if (lower.includes('drizzle'))
+            return 'drizzle';
+        return 'unknown';
+    });
+    // Deduplicate (e.g. two Prisma databases registered)
+    const uniqueAdapters = [...new Set(adapters)];
+    // Collect only the enabled (true) feature flags so the payload stays
+    // compact and never leaks false/undefined entries.
+    const features = [];
+    const adminFeatures = admin.options.features ?? {};
+    for (const [key, val] of Object.entries(adminFeatures)) {
+        if (val === true)
+            features.push(key);
+    }
+    const versions = process.versions;
+    const runtime = versions.bun
+        ? `bun/${versions.bun}`
+        : `node/${versions.node ?? 'unknown'}`;
+    return {
+        instanceId: _instanceId,
+        adapters: uniqueAdapters,
+        resourceCount: admin.resources.length,
+        featureFlags: admin.options.featureFlags ?? [],
+        features,
+        platform: process.platform,
+        runtime,
+    };
+}
+/**
+ * Reset the per-process instance ID (test helper only).
+ * @internal
+ */
+export function _resetInstanceId() {
+    _instanceId = undefined;
+}
+//# sourceMappingURL=collect.js.map

package/dist/collect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.js","sourceRoot":"","sources":["../src/collect.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAG3C,qDAAqD;AACrD,IAAI,WAA+B,CAAA;AAEnC;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAkB;IACrD,IAAI,CAAC,WAAW;QAAE,WAAW,GAAG,MAAM,EAAE,CAAA;IAExC,wEAAwE;IACxE,wEAAwE;IACxE,6BAA6B;IAC7B,MAAM,QAAQ,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACxD,MAAM,GAAG,GAAI,CAAC,CAAC,QAA8B,CAAC,IAAI,IAAI,EAAE,CAAA;QACxD,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,EAAE,CAAA;QAC/B,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,OAAO,QAAQ,CAAA;QAC7C,IAAI,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC;YAAE,OAAO,SAAS,CAAA;QAC/C,OAAO,SAAS,CAAA;IAClB,CAAC,CAAC,CAAA;IAEF,qDAAqD;IACrD,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAA;IAE7C,qEAAqE;IACrE,mDAAmD;IACnD,MAAM,QAAQ,GAAa,EAAE,CAAA;IAC7B,MAAM,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAA;IAClD,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;QACvD,IAAI,GAAG,KAAK,IAAI;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACtC,CAAC;IAED,MAAM,QAAQ,GAAG,OAAO,CAAC,QAA8C,CAAA;IACvE,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG;QAC1B,CAAC,CAAC,OAAO,QAAQ,CAAC,GAAG,EAAE;QACvB,CAAC,CAAC,QAAQ,QAAQ,CAAC,IAAI,IAAI,SAAS,EAAE,CAAA;IAExC,OAAO;QACL,UAAU,EAAE,WAAW;QACvB,QAAQ,EAAE,cAAc;QACxB,aAAa,EAAE,KAAK,CAAC,SAAS,CAAC,MAAM;QACrC,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,YAAY,IAAI,EAAE;QAC9C,QAAQ;QACR,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,OAAO;KACR,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,WAAW,GAAG,SAAS,CAAA;AACzB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { TelemetryInfo } from './types.js';
+export { collectTelemetryInfo, _resetInstanceId } from './collect.js';
+export { reportTelemetry, _resetReported } from './report.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACrE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { collectTelemetryInfo, _resetInstanceId } from './collect.js';
+export { reportTelemetry, _resetReported } from './report.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACrE,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA"}

package/dist/report.d.ts

@@ -0,0 +1,23 @@
+import type { TelemetryInfo } from './types.js';
+/**
+ * Fire-and-forget telemetry ping. Exits immediately when the
+ * `MODERN_ADMIN_TELEMETRY` environment variable is not set to `"1"`.
+ *
+ * The function:
+ * - Never throws — any network error is silently swallowed.
+ * - Pings at most once per process lifetime (subsequent calls are no-ops).
+ * - Times out after 5 s to prevent blocking server startup.
+ * - Sends a single `POST` with the `TelemetryInfo` payload as JSON.
+ *
+ * @param info   Payload built by `collectTelemetryInfo`.
+ * @param opts.endpoint Override the default endpoint (useful in tests).
+ */
+export declare function reportTelemetry(info: TelemetryInfo, opts?: {
+    endpoint?: string;
+}): Promise<void>;
+/**
+ * Reset the "already reported" guard (test helper only).
+ * @internal
+ */
+export declare function _resetReported(): void;
+//# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAQ/C;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,aAAa,EACnB,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3B,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/dist/report.js

@@ -0,0 +1,47 @@
+/** Default endpoint — the license-issuance / telemetry backend. */
+const TELEMETRY_ENDPOINT = 'https://api.modernadminpro.com/telemetry';
+/** Guard against double-pings from hot-reload without a process restart. */
+let _reported = false;
+/**
+ * Fire-and-forget telemetry ping. Exits immediately when the
+ * `MODERN_ADMIN_TELEMETRY` environment variable is not set to `"1"`.
+ *
+ * The function:
+ * - Never throws — any network error is silently swallowed.
+ * - Pings at most once per process lifetime (subsequent calls are no-ops).
+ * - Times out after 5 s to prevent blocking server startup.
+ * - Sends a single `POST` with the `TelemetryInfo` payload as JSON.
+ *
+ * @param info   Payload built by `collectTelemetryInfo`.
+ * @param opts.endpoint Override the default endpoint (useful in tests).
+ */
+export async function reportTelemetry(info, opts) {
+    if (process.env.MODERN_ADMIN_TELEMETRY !== '1')
+        return;
+    if (_reported)
+        return;
+    _reported = true;
+    const url = opts?.endpoint ?? TELEMETRY_ENDPOINT;
+    try {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 5_000);
+        await fetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(info),
+            signal: ac.signal,
+        });
+        clearTimeout(timer);
+    }
+    catch {
+        // Telemetry failures must NEVER surface to or affect the host application.
+    }
+}
+/**
+ * Reset the "already reported" guard (test helper only).
+ * @internal
+ */
+export function _resetReported() {
+    _reported = false;
+}
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAEA,mEAAmE;AACnE,MAAM,kBAAkB,GAAG,0CAA0C,CAAA;AAErE,4EAA4E;AAC5E,IAAI,SAAS,GAAG,KAAK,CAAA;AAErB;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAmB,EACnB,IAA4B;IAE5B,IAAI,OAAO,CAAC,GAAG,CAAC,sBAAsB,KAAK,GAAG;QAAE,OAAM;IACtD,IAAI,SAAS;QAAE,OAAM;IACrB,SAAS,GAAG,IAAI,CAAA;IAEhB,MAAM,GAAG,GAAG,IAAI,EAAE,QAAQ,IAAI,kBAAkB,CAAA;IAChD,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAA;QAChC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,CAAC,CAAA;QACjD,MAAM,KAAK,CAAC,GAAG,EAAE;YACf,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;YAC1B,MAAM,EAAE,EAAE,CAAC,MAAM;SAClB,CAAC,CAAA;QACF,YAAY,CAAC,KAAK,CAAC,CAAA;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;IAC7E,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc;IAC5B,SAAS,GAAG,KAAK,CAAA;AACnB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shape of a single telemetry ping. Contains only technical/aggregate data —
+ * no resource names, record contents, user identifiers, or secrets.
+ *
+ * The `instanceId` is a UUID v7 generated once per process start. It is
+ * **not** persisted to disk and cannot be used to track installations across
+ * restarts. Its only purpose is server-side deduplication of rapid re-pings
+ * from the same running process (e.g., on hot-reload).
+ */
+export interface TelemetryInfo {
+    /** UUID v7, generated fresh each process start, never persisted. */
+    instanceId: string;
+    /**
+     * Short adapter name(s) in use — derived from the adapter `Database`
+     * constructor name (e.g. `"prisma"`, `"drizzle"`, `"unknown"`).
+     * Does not reveal schema details.
+     */
+    adapters: string[];
+    /** Total number of registered resources (no names). */
+    resourceCount: number;
+    /**
+     * Active commercial feature flags — the string list passed to
+     * `new ModernAdmin({ featureFlags: [...] })`. Consumers who don't use
+     * Pro packages always see `[]` here.
+     */
+    featureFlags: string[];
+    /**
+     * Enabled admin-subsystem capabilities (keys from `AdminFeatures`).
+     * Only the `true` entries are included to keep payloads compact.
+     */
+    features: string[];
+    /** `process.platform` value (e.g. `"linux"`, `"darwin"`, `"win32"`). */
+    platform: string;
+    /**
+     * Runtime and version string. `"bun/1.3.13"` or `"node/20.0.0"`,
+     * depending on which runtime executes the server.
+     */
+    runtime: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAA;IAClB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,uDAAuD;IACvD,aAAa,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB;;;OAGG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@modern-admin/telemetry",
+  "version": "0.1.0",
+  "description": "Opt-in usage telemetry for Modern Admin (privacy-first, MODERN_ADMIN_TELEMETRY=1 required).",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/modern-admin/modern-admin.git",
+    "directory": "packages/telemetry"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "peerDependencies": {
+    "@modern-admin/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@modern-admin/core": "0.1.0",
+    "@modern-admin/tsconfig": "0.1.0",
+    "@types/bun": "^1.3.13",
+    "typescript": "^6.0.3"
+  }
+}

package/src/collect.ts

@@ -0,0 +1,63 @@
+import type { ModernAdmin } from '@modern-admin/core'
+import { uuidv7 } from '@modern-admin/core'
+import type { TelemetryInfo } from './types.js'
+
+/** Stable per-process identifier (not persisted). */
+let _instanceId: string | undefined
+
+/**
+ * Build a `TelemetryInfo` snapshot from a running `ModernAdmin` instance.
+ * Reads only technical/aggregate data — no resource names, record
+ * contents, user data, or secrets are captured.
+ *
+ * This function is pure (no network I/O). Pass the result to
+ * `reportTelemetry` to ship it.
+ */
+export function collectTelemetryInfo(admin: ModernAdmin): TelemetryInfo {
+  if (!_instanceId) _instanceId = uuidv7()
+
+  // Derive a short adapter name from the Database constructor class name.
+  // Examples: "PrismaDatabase" → "prisma", "DrizzleDatabase" → "drizzle",
+  // anything else → "unknown".
+  const adapters = (admin.options.adapters ?? []).map((a) => {
+    const raw = (a.Database as { name?: string }).name ?? ''
+    const lower = raw.toLowerCase()
+    if (lower.includes('prisma')) return 'prisma'
+    if (lower.includes('drizzle')) return 'drizzle'
+    return 'unknown'
+  })
+
+  // Deduplicate (e.g. two Prisma databases registered)
+  const uniqueAdapters = [...new Set(adapters)]
+
+  // Collect only the enabled (true) feature flags so the payload stays
+  // compact and never leaks false/undefined entries.
+  const features: string[] = []
+  const adminFeatures = admin.options.features ?? {}
+  for (const [key, val] of Object.entries(adminFeatures)) {
+    if (val === true) features.push(key)
+  }
+
+  const versions = process.versions as Record<string, string | undefined>
+  const runtime = versions.bun
+    ? `bun/${versions.bun}`
+    : `node/${versions.node ?? 'unknown'}`
+
+  return {
+    instanceId: _instanceId,
+    adapters: uniqueAdapters,
+    resourceCount: admin.resources.length,
+    featureFlags: admin.options.featureFlags ?? [],
+    features,
+    platform: process.platform,
+    runtime,
+  }
+}
+
+/**
+ * Reset the per-process instance ID (test helper only).
+ * @internal
+ */
+export function _resetInstanceId(): void {
+  _instanceId = undefined
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export type { TelemetryInfo } from './types.js'
+export { collectTelemetryInfo, _resetInstanceId } from './collect.js'
+export { reportTelemetry, _resetReported } from './report.js'

package/src/report.ts

@@ -0,0 +1,52 @@
+import type { TelemetryInfo } from './types.js'
+
+/** Default endpoint — the license-issuance / telemetry backend. */
+const TELEMETRY_ENDPOINT = 'https://api.modernadminpro.com/telemetry'
+
+/** Guard against double-pings from hot-reload without a process restart. */
+let _reported = false
+
+/**
+ * Fire-and-forget telemetry ping. Exits immediately when the
+ * `MODERN_ADMIN_TELEMETRY` environment variable is not set to `"1"`.
+ *
+ * The function:
+ * - Never throws — any network error is silently swallowed.
+ * - Pings at most once per process lifetime (subsequent calls are no-ops).
+ * - Times out after 5 s to prevent blocking server startup.
+ * - Sends a single `POST` with the `TelemetryInfo` payload as JSON.
+ *
+ * @param info   Payload built by `collectTelemetryInfo`.
+ * @param opts.endpoint Override the default endpoint (useful in tests).
+ */
+export async function reportTelemetry(
+  info: TelemetryInfo,
+  opts?: { endpoint?: string },
+): Promise<void> {
+  if (process.env.MODERN_ADMIN_TELEMETRY !== '1') return
+  if (_reported) return
+  _reported = true
+
+  const url = opts?.endpoint ?? TELEMETRY_ENDPOINT
+  try {
+    const ac = new AbortController()
+    const timer = setTimeout(() => ac.abort(), 5_000)
+    await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(info),
+      signal: ac.signal,
+    })
+    clearTimeout(timer)
+  } catch {
+    // Telemetry failures must NEVER surface to or affect the host application.
+  }
+}
+
+/**
+ * Reset the "already reported" guard (test helper only).
+ * @internal
+ */
+export function _resetReported(): void {
+  _reported = false
+}

package/src/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Shape of a single telemetry ping. Contains only technical/aggregate data —
+ * no resource names, record contents, user identifiers, or secrets.
+ *
+ * The `instanceId` is a UUID v7 generated once per process start. It is
+ * **not** persisted to disk and cannot be used to track installations across
+ * restarts. Its only purpose is server-side deduplication of rapid re-pings
+ * from the same running process (e.g., on hot-reload).
+ */
+export interface TelemetryInfo {
+  /** UUID v7, generated fresh each process start, never persisted. */
+  instanceId: string
+  /**
+   * Short adapter name(s) in use — derived from the adapter `Database`
+   * constructor name (e.g. `"prisma"`, `"drizzle"`, `"unknown"`).
+   * Does not reveal schema details.
+   */
+  adapters: string[]
+  /** Total number of registered resources (no names). */
+  resourceCount: number
+  /**
+   * Active commercial feature flags — the string list passed to
+   * `new ModernAdmin({ featureFlags: [...] })`. Consumers who don't use
+   * Pro packages always see `[]` here.
+   */
+  featureFlags: string[]
+  /**
+   * Enabled admin-subsystem capabilities (keys from `AdminFeatures`).
+   * Only the `true` entries are included to keep payloads compact.
+   */
+  features: string[]
+  /** `process.platform` value (e.g. `"linux"`, `"darwin"`, `"win32"`). */
+  platform: string
+  /**
+   * Runtime and version string. `"bun/1.3.13"` or `"node/20.0.0"`,
+   * depending on which runtime executes the server.
+   */
+  runtime: string
+}