@acamarata/telemetry

Opt-in anonymous usage telemetry helper for @acamarata packages.

Zero dependencies. Zero PII. Fire-and-forget. Off by default.

Install

npm install @acamarata/telemetry
# or
pnpm add @acamarata/telemetry

Usage

import { track, isEnabled, getConfig } from '@acamarata/telemetry';

// Send a ping — only fires if ACAMARATA_TELEMETRY=1 or { enabled: true }
await track('init', {
  package: 'hijri-core',
  version: '1.0.4',
  event: 'init',
  enabled: true,   // or rely on the env var
});

// Check state without sending anything
console.log(isEnabled()); // false by default

// Inspect resolved config
const cfg = getConfig({ url: 'https://custom.example.com' });
// { enabled: false, url: '...', ingestUrl: '.../ingest' }

Opt-in / privacy

Telemetry is off by default. Nothing is sent unless you opt in.

Enable by setting an environment variable:

ACAMARATA_TELEMETRY=1 node your-app.js

What is sent when enabled: package name, package version, event name, operation count, OS platform, Node major version, and CPU architecture. No hostnames, usernames, IPs, file paths, or any user-identifying data. See TELEMETRY.md for the complete field list and server policy.

First-run notice

When telemetry is off and your terminal is a TTY, a one-time notice is printed to stderr explaining how to enable it. Suppress the notice:

ACAMARATA_TELEMETRY_SILENT=1 node your-app.js

The notice is suppressed automatically in CI and pipes (isTTY check).

API

track(event, opts?): Promise<boolean>

Send a usage ping. Returns true if telemetry is enabled and a send was attempted, false if disabled. Never throws. Never rejects. Hard 1000 ms timeout.

isEnabled(opts?): boolean

Check whether telemetry is active for the given options. No network call.

getConfig(opts?): ResolvedTelemetryConfig

Return the resolved configuration (enabled, url, ingestUrl). Useful for testing.

Options (TelemetryOptions)

| Field | Type | Description | |-----------|-----------|-------------| | package | string | Package name (e.g. "hijri-core") | | version | string | Package version | | event | string | Event name passed to track() | | count | number | Operation count (default 1) | | enabled | boolean | Override the env var on/off | | url | string | Override the ingest base URL |

Environment variables

| Variable | Effect | |-----------------------------|--------| | ACAMARATA_TELEMETRY=1 | Enable telemetry | | ACAMARATA_TELEMETRY_URL | Override ingest base URL | | ACAMARATA_TELEMETRY_SILENT=1 | Suppress first-run notice |

License

MIT. See LICENSE.