{"_id":"@acamarata/telemetry","name":"@acamarata/telemetry","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@acamarata/telemetry","version":"0.1.0","description":"Opt-in anonymous usage telemetry helper for @acamarata packages. Zero PII, fire-and-forget, OFF by default.","author":{"name":"Aric Camarata"},"license":"MIT","main":"./dist/index.cjs","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.cjs"},"./package.json":"./package.json"},"sideEffects":false,"engines":{"node":">=20"},"packageManager":"pnpm@10.30.1","scripts":{"build":"tsup","typecheck":"tsc --noEmit","pretest":"tsup","test":"node --test test.mjs && node --test test-cjs.cjs","prepack":"pnpm run build","lint":"eslint .","format":"prettier --write src/","format:check":"prettier --check src/","coverage":"c8 --reporter=lcov --reporter=text node test.mjs","postbuild":"cp dist/index.d.ts dist/index.d.mts","test:vitest":"vitest run"},"keywords":["telemetry","analytics","opt-in","anonymous","privacy","acamarata","typescript"],"devDependencies":{"@acamarata/eslint-config":"^0.1.0","@acamarata/prettier-config":"^0.1.0","@acamarata/tsconfig":"^0.1.0","@eslint/js":"^10.0.1","@types/node":"^22.15.0","@typescript-eslint/eslint-plugin":"^8.56.1","@typescript-eslint/parser":"^8.56.1","c8":"^10.1.0","eslint":"^10.0.3","eslint-config-prettier":"^10.1.8","prettier":"^3.8.1","tsup":"^8.0.0","typescript":"^5.5.0","typescript-eslint":"^8.56.1","vitest":"^2.1.9"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"repository":{"type":"git","url":"git+https://github.com/acamarata/telemetry.git"},"homepage":"https://github.com/acamarata/telemetry#readme","bugs":{"url":"https://github.com/acamarata/telemetry/issues"},"type":"module","prettier":"@acamarata/prettier-config","_id":"@acamarata/telemetry@0.1.0","_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-iP09ZD0bHencHLbv6kQZDgwN9crLCWGKxmiMrfJjhBCoWTgv4koSgg0Li/LFKwCCFluua6orj9fVeQ8eqcJXSQ==","shasum":"1b341f2203fe6f976f77529d1817e6b9514e8eb4","tarball":"https://registry.npmjs.org/@acamarata/telemetry/-/telemetry-0.1.0.tgz","fileCount":9,"unpackedSize":26283,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHFZC7ggpv0oxsimoV/Mn7MB+wLKOms+XniStmSapnkZAiEAyF09YNZqSfHfzUjaMBmgCblBx7qTut6u1DRxA/E75tY="}]},"_npmUser":{"name":"acamarata","email":"alisalaah@gmail.com"},"directories":{},"maintainers":[{"name":"acamarata","email":"alisalaah@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/telemetry_0.1.0_1782848451839_0.880376459219226"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-30T19:40:51.660Z","0.1.0":"2026-06-30T19:40:51.993Z","modified":"2026-06-30T19:40:52.300Z"},"maintainers":[{"name":"acamarata","email":"alisalaah@gmail.com"}],"description":"Opt-in anonymous usage telemetry helper for @acamarata packages. Zero PII, fire-and-forget, OFF by default.","homepage":"https://github.com/acamarata/telemetry#readme","keywords":["telemetry","analytics","opt-in","anonymous","privacy","acamarata","typescript"],"repository":{"type":"git","url":"git+https://github.com/acamarata/telemetry.git"},"author":{"name":"Aric Camarata"},"bugs":{"url":"https://github.com/acamarata/telemetry/issues"},"license":"MIT","readme":"# @acamarata/telemetry\n\nOpt-in anonymous usage telemetry helper for `@acamarata` packages.\n\nZero dependencies. Zero PII. Fire-and-forget. Off by default.\n\n## Install\n\n```sh\nnpm install @acamarata/telemetry\n# or\npnpm add @acamarata/telemetry\n```\n\n## Usage\n\n```ts\nimport { track, isEnabled, getConfig } from '@acamarata/telemetry';\n\n// Send a ping — only fires if ACAMARATA_TELEMETRY=1 or { enabled: true }\nawait track('init', {\n  package: 'hijri-core',\n  version: '1.0.4',\n  event: 'init',\n  enabled: true,   // or rely on the env var\n});\n\n// Check state without sending anything\nconsole.log(isEnabled()); // false by default\n\n// Inspect resolved config\nconst cfg = getConfig({ url: 'https://custom.example.com' });\n// { enabled: false, url: '...', ingestUrl: '.../ingest' }\n```\n\n## Opt-in / privacy\n\nTelemetry is **off by default**. Nothing is sent unless you opt in.\n\nEnable by setting an environment variable:\n\n```sh\nACAMARATA_TELEMETRY=1 node your-app.js\n```\n\nWhat is sent when enabled: package name, package version, event name, operation\ncount, OS platform, Node major version, and CPU architecture. No hostnames,\nusernames, IPs, file paths, or any user-identifying data. See [TELEMETRY.md](./TELEMETRY.md)\nfor the complete field list and server policy.\n\n## First-run notice\n\nWhen telemetry is off and your terminal is a TTY, a one-time notice is printed to\nstderr explaining how to enable it. Suppress the notice:\n\n```sh\nACAMARATA_TELEMETRY_SILENT=1 node your-app.js\n```\n\nThe notice is suppressed automatically in CI and pipes (`isTTY` check).\n\n## API\n\n### `track(event, opts?): Promise<boolean>`\n\nSend a usage ping. Returns `true` if telemetry is enabled and a send was attempted,\n`false` if disabled. Never throws. Never rejects. Hard 1000 ms timeout.\n\n### `isEnabled(opts?): boolean`\n\nCheck whether telemetry is active for the given options. No network call.\n\n### `getConfig(opts?): ResolvedTelemetryConfig`\n\nReturn the resolved configuration (`enabled`, `url`, `ingestUrl`). Useful for testing.\n\n### Options (`TelemetryOptions`)\n\n| Field     | Type      | Description |\n|-----------|-----------|-------------|\n| `package` | `string`  | Package name (e.g. `\"hijri-core\"`) |\n| `version` | `string`  | Package version |\n| `event`   | `string`  | Event name passed to `track()` |\n| `count`   | `number`  | Operation count (default 1) |\n| `enabled` | `boolean` | Override the env var on/off |\n| `url`     | `string`  | Override the ingest base URL |\n\n## Environment variables\n\n| Variable                    | Effect |\n|-----------------------------|--------|\n| `ACAMARATA_TELEMETRY=1`     | Enable telemetry |\n| `ACAMARATA_TELEMETRY_URL`   | Override ingest base URL |\n| `ACAMARATA_TELEMETRY_SILENT=1` | Suppress first-run notice |\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","readmeFilename":"README.md","_rev":"1-703c2396ecca14344881cc7e818b5327"}