@medusajs/telemetry 2.22.0-snapshot-20261020204851 → 2.22.0

package/AGENTS.md

@@ -0,0 +1,36 @@
+# @medusajs/telemetry
+
+Anonymous usage telemetry for the Medusa CLI and server. Used internally by `@medusajs/cli`, `@medusajs/medusa` commands, `@medusajs/framework` (feature flags), and `create-medusa-app`; applications never configure it directly.
+
+## Using this package
+
+- Opting out (end users): set `MEDUSA_DISABLE_TELEMETRY=true` or run `npx medusa telemetry --disable` (persists `telemetry.enabled: false`).
+  - https://docs.medusajs.com/learn/resources/usage.md
+  - https://docs.medusajs.com/resources/medusa-cli/commands/telemtry.md
+- Exports (from `src/index.js`):
+  - `track(event, data?)`: queue an event, e.g. `track("CLI_START")`, `track("CLI_USER", { with_id: !!id })`
+  - `setTelemetryEnabled(enabled = true)`: backs the `medusa telemetry` command in `packages/cli/medusa-cli/src/create-cli.ts`
+  - `trackFeatureFlag(flag)`, `trackInstallation(installation, "plugin" | "module")`: attached to every later event
+  - `flush`, `Store`, `Telemeter`
+- `Store` doubles as Medusa's persistent per-machine config store; other packages use it for non-telemetry flags (`star.prompted` in `packages/medusa/src/commands/develop.ts`, the Claude Code plugin prompt in `packages/medusa/src/utils/claude-code-plugin.ts`).
+
+## Architecture
+
+- Plain JavaScript (`src/*.js`, compiled via `allowJs`); no types beyond generated declarations.
+- Flow: `track` -> `Telemeter.enqueue_` -> `Store.addEvent` appends a JSON line to `events.json` (`util/outbox-store.js`) next to the `configstore` file named `medusa` -> when `flushAt` (20 events), `maxQueueSize` (500 KB) or `flushInterval` (10 s) is hit, `util/create-flush.js` forks `util/send.js` as a detached, unref'd child -> `util/telemetry-dispatcher.js` POSTs `{ batch, timestamp }` with `axios-retry` (3 retries on network errors, 5xx, 429).
+- Every event carries `machine_id` (stored as `telemetry.machine_id`), OS/CI info (`util/is-ci.js`), the resolved `@medusajs/medusa` and `@medusajs/cli` versions, feature flags, modules, and plugins.
+- Env vars: `MEDUSA_DISABLE_TELEMETRY`, `MEDUSA_TELEMETRY_VERBOSE` (logs flush/send errors; also makes the forked sender inherit stdio), `MEDUSA_TELEMETRY_HOST` / `MEDUSA_TELEMETRY_PATH` (default `https://telemetry.medusa-commerce.com` + `/batch`).
+
+## Development
+
+- `yarn build`, `yarn watch`, `yarn test` (`jest --passWithNoTests src`; there are currently no tests).
+- The `start` script (nodemon on `plugins/`) is stale; don't rely on it.
+- To debug locally, point `MEDUSA_TELEMETRY_HOST` at a local server and set `MEDUSA_TELEMETRY_VERBOSE=true`.
+
+## Gotchas
+
+- Importing the package has side effects: it constructs a `Telemeter`, reads/writes config, may print the opt-out notice (outside CI) on first run, and registers `process.on("exit", flush)`.
+- `postinstall` runs `node dist/postinstall.js || true` to show the opt-out notice on install; it must never throw.
+- `MEDUSA_DISABLE_TELEMETRY` only stops events from being written (`Store.addEvent`); the on/off decision for flushing comes from the stored `telemetry.enabled` config, which defaults to `true` when unset.
+- If `configstore` can't write (read-only home dir), `Store` falls back to `InMemoryConfigStore` with a throwaway `not-a-machine-id-*` id and the OS temp dir as base path.
+- The sender is a separate process: a failed POST writes the batch back to `events.json`, but events can be lost if that process dies mid-send (see comment in `outbox-store.js`).

package/README.md

@@ -0,0 +1,70 @@
+<p align="center">
+  <a href="https://www.medusajs.com">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
+    </picture>
+  </a>
+</p>
+<h1 align="center">
+  @medusajs/telemetry
+</h1>
+
+<h4 align="center">
+  <a href="https://docs.medusajs.com">Documentation</a> |
+  <a href="https://www.medusajs.com">Website</a>
+</h4>
+
+<p align="center">
+  Building blocks for digital commerce
+</p>
+<p align="center">
+  <a href="https://github.com/medusajs/medusa/blob/develop/LICENSE">
+    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="Medusa is released under the MIT license." />
+  </a>
+  <a href="https://github.com/medusajs/medusa/blob/develop/CONTRIBUTING.md">
+    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
+  </a>
+  <a href="https://discord.gg/xpCwq3Kfn8">
+    <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
+  </a>
+  <a href="https://twitter.com/intent/follow?screen_name=medusajs">
+    <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
+  </a>
+</p>
+
+`@medusajs/telemetry` collects anonymous, non-sensitive usage data from the Medusa CLI and application, such as OS and Node.js version and the Medusa version in use. It is an internal dependency of `@medusajs/medusa`, `@medusajs/framework`, and `@medusajs/cli`; you don't install or call it directly, but you can opt out of it.
+
+## At a glance
+
+| | |
+| --- | --- |
+| Package | `@medusajs/telemetry` |
+| Type | Internal tooling |
+
+## Opting out
+
+Set the environment variable:
+
+```bash
+MEDUSA_DISABLE_TELEMETRY=true
+```
+
+Or run the CLI command in your project:
+
+```bash
+npx medusa telemetry --disable
+```
+
+## Configuration
+
+| Environment variable | Description | Default |
+| --- | --- | --- |
+| `MEDUSA_DISABLE_TELEMETRY` | Disables telemetry collection when truthy. | - |
+| `MEDUSA_TELEMETRY_VERBOSE` | Logs telemetry activity to the console when truthy. | - |
+
+## Resources
+
+- [Usage information](https://docs.medusajs.com/learn/resources/usage)
+- [`medusa telemetry` command](https://docs.medusajs.com/resources/medusa-cli/commands/telemtry)

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export function trackFeatureFlag(flag: any): void;
 export function trackInstallation(installation: any, type: any): void;
+export const flush: (() => Promise<void>) | undefined;
 export function track(event: any, data?: {}): void;
 export function setTelemetryEnabled(enabled?: boolean): void;
 export { default as Store } from "./store";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AA8CA,kDAEC;AAED,sEAWC;AAvBM,mDAEN;AAEM,6DAEN"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":"AAmBA,kDAEC;AAED,sEASC;AA3BD,sDAA+D;AAMxD,mDAEN;AAEM,6DAEN"}

package/dist/index.js

@@ -3,62 +3,36 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Telemeter = exports.Store = exports.setTelemetryEnabled = exports.track = void 0;
+exports.Telemeter = exports.Store = exports.setTelemetryEnabled = exports.track = exports.flush = void 0;
 exports.trackFeatureFlag = trackFeatureFlag;
 exports.trackInstallation = trackInstallation;
 const telemeter_1 = __importDefault(require("./telemeter"));
 const create_flush_1 = __importDefault(require("./util/create-flush"));
-/**
- * Creating the telemeter reads its config from disk and inspects the
- * environment, and tracking writes to the outbox synchronously. Neither should
- * happen while the importing process boots, so the telemeter is created on
- * first use and tracked events are processed shortly after, or on exit.
- */
-const TRACKING_DELAY_MS = 2000;
-let telemeter;
-const pending = [];
-let drainTimer;
-function getTelemeter() {
-    telemeter ??= new telemeter_1.default();
-    return telemeter;
+const telemeter = new telemeter_1.default();
+exports.flush = (0, create_flush_1.default)(telemeter.isTrackingEnabled());
+if (exports.flush) {
+    process.on(`exit`, exports.flush);
 }
-function drain() {
-    clearTimeout(drainTimer);
-    drainTimer = undefined;
-    while (pending.length) {
-        pending.shift()(getTelemeter());
-    }
-}
-function defer(fn) {
-    pending.push(fn);
-    drainTimer ??= setTimeout(drain, TRACKING_DELAY_MS).unref();
-}
-process.on(`exit`, () => {
-    drain();
-    (0, create_flush_1.default)(getTelemeter().isTrackingEnabled())?.();
-});
 const track = (event, data = {}) => {
-    defer((t) => t.track(event, data));
+    telemeter.track(event, data);
 };
 exports.track = track;
 const setTelemetryEnabled = (enabled = true) => {
-    getTelemeter().setTelemetryEnabled(enabled);
+    telemeter.setTelemetryEnabled(enabled);
 };
 exports.setTelemetryEnabled = setTelemetryEnabled;
 function trackFeatureFlag(flag) {
-    defer((t) => t.trackFeatureFlag(flag));
+    telemeter.trackFeatureFlag(flag);
 }
 function trackInstallation(installation, type) {
-    defer((t) => {
-        switch (type) {
-            case `plugin`:
-                t.trackPlugin(installation);
-                break;
-            case `module`:
-                t.trackModule(installation);
-                break;
-        }
-    });
+    switch (type) {
+        case `plugin`:
+            telemeter.trackPlugin(installation);
+            break;
+        case `module`:
+            telemeter.trackModule(installation);
+            break;
+    }
 }
 var store_1 = require("./store");
 Object.defineProperty(exports, "Store", { enumerable: true, get: function () { return __importDefault(store_1).default; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medusajs/telemetry",
-  "version": "2.22.0-snapshot-20261020204851",
+  "version": "2.22.0",
   "description": "Telemetry for Medusa",
   "main": "dist/index.js",
   "repository": {
@@ -18,8 +18,12 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "AGENTS.md"
   ],
+  "llms": "https://docs.medusajs.com/llms.txt",
+  "llmsFull": "https://docs.medusajs.com/llms-full.txt",
+  "mcpServer": "https://docs.medusajs.com/mcp",
   "author": "Sebastian Rindom",
   "license": "MIT",
   "scripts": {