add opt-in anonymous telemetry (#1)

* add opt-in telemetry via @acamarata/telemetry (off by default)

* chore: update lockfile for @acamarata/telemetry devDep

* chore: fix prettier formatting on telemetry import

README.md

@@ -73,6 +73,11 @@ day-start determination is out of scope.
 - [luxon-hijri](https://github.com/acamarata/luxon-hijri): Hijri support for Luxon
 - [pray-calc](https://github.com/acamarata/pray-calc): Islamic prayer times
 
+## Telemetry
+
+This package supports opt-in anonymous usage telemetry — off by default.
+Enable: `ACAMARATA_TELEMETRY=1`. See [TELEMETRY.md](./TELEMETRY.md) for what is sent and how to disable.
+
 ## License
 
 MIT. Copyright (c) 2026 Aric Camarata. See [LICENSE](LICENSE).

TELEMETRY.md

@@ -0,0 +1,8 @@
+# Telemetry Disclosure
+
+This package supports opt-in anonymous usage telemetry via [`@acamarata/telemetry`](https://github.com/acamarata/telemetry).
+
+Telemetry is **off by default**. No data is sent unless you set `ACAMARATA_TELEMETRY=1`.
+
+Full disclosure (what is sent, where it goes, how to disable):
+[github.com/acamarata/telemetry/blob/main/TELEMETRY.md](https://github.com/acamarata/telemetry/blob/main/TELEMETRY.md)

package.json

@@ -81,7 +81,8 @@
     "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^5.5.0",
-    "typescript-eslint": "^8.56.1"
+    "typescript-eslint": "^8.56.1",
+    "@acamarata/telemetry": "^0.1.0"
   },
   "publishConfig": {
     "access": "public",

pnpm-lock.yaml

@@ -14,6 +14,9 @@ importers:
       '@acamarata/prettier-config':
         specifier: ^0.1.0
         version: 0.1.0(prettier@3.8.1)
+      '@acamarata/telemetry':
+        specifier: ^0.1.0
+        version: 0.1.0
       '@acamarata/tsconfig':
         specifier: ^0.1.0
         version: 0.1.0
@@ -87,6 +90,10 @@ packages:
     peerDependencies:
       prettier: '>=3.0.0'
 
+  '@acamarata/telemetry@0.1.0':
+    resolution: {integrity: sha512-iP09ZD0bHencHLbv6kQZDgwN9crLCWGKxmiMrfJjhBCoWTgv4koSgg0Li/LFKwCCFluua6orj9fVeQ8eqcJXSQ==}
+    engines: {node: '>=20'}
+
   '@acamarata/tsconfig@0.1.0':
     resolution: {integrity: sha512-bgzyBak43mE+0HhduZX3cvaPjKcggtGGZZMjr35qtYWolsIWgZ9nx7OOswbVYoU35qoUv6rZ0mTK6GbZ8QTYjw==}
     engines: {node: '>=20'}
@@ -1208,6 +1215,8 @@ snapshots:
     dependencies:
       prettier: 3.8.1
 
+  '@acamarata/telemetry@0.1.0': {}
+
   '@acamarata/tsconfig@0.1.0': {}
 
   '@bcoe/v8-coverage@1.0.2': {}

src/index.ts

@@ -10,3 +10,12 @@ import { FcnaCalendar } from "./calendars/FcnaCalendar";
 
 export const uaqCalendar = new UaqCalendar();
 export const fcnaCalendar = new FcnaCalendar();
+
+// ── Opt-in anonymous telemetry ────────────────────────────────────────────────
+// Off by default. Enable: ACAMARATA_TELEMETRY=1
+// What is sent + how to disable: https://github.com/acamarata/telemetry/blob/main/TELEMETRY.md
+import("@acamarata/telemetry")
+  .then(({ track }) => track("load", { package: "temporal-hijri", version: "1.0.3" }))
+  .catch(() => {
+    // telemetry not installed or disabled — that is fine
+  });