From 0cd9a66c5cf0c001a7bf69685f25f10c42754e63 Mon Sep 17 00:00:00 2001
From: Aric Camarata <aric.camarata@gmail.com>
Date: Tue, 30 Jun 2026 14:59:31 -0400
Subject: [PATCH] add opt-in telemetry via @acamarata/telemetry (off by
 default)

---
 README.md    |  5 +++++
 TELEMETRY.md |  8 ++++++++
 package.json |  3 ++-
 src/index.ts | 11 +++++++++++
 4 files changed, 26 insertions(+), 1 deletion(-)
 create mode 100644 TELEMETRY.md

diff --git a/README.md b/README.md
index 23f4e5f..8e07112 100644
--- a/README.md
+++ b/README.md
@@ -56,6 +56,11 @@ Full API reference, algorithm design, and spherical trigonometry notes: [GitHub
 
 Ka'bah coordinates verified against published GPS surveys and cross-checked with satellite imagery. Forward azimuth formula follows standard spherical trigonometry as used in aviation and geodesy.
 
+## 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](LICENSE)
diff --git a/TELEMETRY.md b/TELEMETRY.md
new file mode 100644
index 0000000..99cfaa4
--- /dev/null
+++ b/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)
diff --git a/package.json b/package.json
index 432117d..aa249af 100644
--- a/package.json
+++ b/package.json
@@ -85,7 +85,8 @@
     "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.32.1"
+    "typescript-eslint": "^8.32.1",
+    "@acamarata/telemetry": "^0.1.0"
   },
   "type": "module",
   "packageManager": "pnpm@10.11.1",
diff --git a/src/index.ts b/src/index.ts
index 351b3ec..4888fb3 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -146,3 +146,14 @@ export function distanceKm(lat1: number, lng1: number, lat2: number, lng2: numbe
     Math.sin(dLat / 2) ** 2 + Math.cos(lat1 * DEG) * Math.cos(lat2 * DEG) * Math.sin(dLng / 2) ** 2;
   return EARTH_RADIUS_KM * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
 }
+
+// ── 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: '@acamarata/qibla', version: '1.1.2' }),
+  )
+  .catch(() => {
+    // telemetry not installed or disabled — that is fine
+  });