add opt-in anonymous telemetry (#2)

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

* chore: update lockfile for @acamarata/telemetry devDep

README.md

@@ -66,6 +66,11 @@ Full API reference, dynamic algorithm details, traditional method table, and hig
 
 Solar position calculations use [nrel-spa](https://github.com/acamarata/nrel-spa), a port of the NREL SPA by Ibrahim Reda and Afshin Andreas. The seasonal twilight model builds on the work of Khalid Shaukat (Moonsighting Committee Worldwide).
 
+## 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) 2023-2026 Aric Camarata.

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)

eslint.config.mjs

@@ -5,10 +5,14 @@ import { typescript } from '@acamarata/eslint-config';
 
 export default [
   {
+    files: ['src/**/*.ts'],
     plugins: { '@typescript-eslint': tsPlugin },
-    languageOptions: { parser: tsParser },
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: { project: true, tsconfigRootDir: import.meta.dirname },
     },
-  ...typescript,
+  },
+  ...typescript.map((cfg) => ({ ...cfg, files: ['src/**/*.ts'] })),
   eslintConfigPrettier,
   {
     ignores: ['dist/', 'node_modules/', 'test.mjs', 'test-cjs.cjs'],

package.json

@@ -30,7 +30,7 @@
     "lint": "eslint src/",
     "format": "prettier --write src/",
     "format:check": "prettier --check src/",
-    "prepublishOnly": "tsup",
+    "prepack": "pnpm run build",
     "coverage": "c8 --reporter=lcov --reporter=text node test.mjs",
     "docs": "typedoc --out .github/wiki/api src/index.ts",
     "postbuild": "cp dist/index.d.ts dist/index.d.mts"
@@ -74,11 +74,13 @@
   },
   "devDependencies": {
     "@acamarata/eslint-config": "^0.1.0",
-    "c8": "^10.1.3",
     "@acamarata/prettier-config": "^0.1.0",
     "@acamarata/tsconfig": "^0.1.0",
     "@eslint/js": "^10.0.1",
     "@types/node": "^25.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "c8": "^10.1.3",
     "eslint": "^10.0.3",
     "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.8.1",
@@ -86,7 +88,8 @@
     "typedoc": "^0.28.19",
     "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1"
+    "typescript-eslint": "^8.56.1",
+    "@acamarata/telemetry": "^0.1.0"
   },
   "type": "module",
   "packageManager": "pnpm@10.11.1",

pnpm-lock.yaml

@@ -18,6 +18,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
@@ -27,6 +30,12 @@ importers:
       '@types/node':
         specifier: ^25.3.0
         version: 25.3.0
+      '@typescript-eslint/eslint-plugin':
+        specifier: ^8.56.1
+        version: 8.56.1(@typescript-eslint/parser@8.56.1(eslint@10.0.3)(typescript@5.9.3))(eslint@10.0.3)(typescript@5.9.3)
+      '@typescript-eslint/parser':
+        specifier: ^8.56.1
+        version: 8.56.1(eslint@10.0.3)(typescript@5.9.3)
       c8:
         specifier: ^10.1.3
         version: 10.1.3
@@ -79,6 +88,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'}
@@ -1227,6 +1240,8 @@ snapshots:
     dependencies:
       prettier: 3.8.1
 
+  '@acamarata/telemetry@0.1.0': {}
+
   '@acamarata/tsconfig@0.1.0': {}
 
   '@bcoe/v8-coverage@1.0.2': {}

src/calcTimes.ts

@@ -2,9 +2,9 @@
  * Formatted prayer times using the PrayCalc Dynamic Method.
  */
 
-import { formatTime } from 'nrel-spa';
-import { getTimes } from './getTimes.js';
-import type { FormattedPrayerTimes } from './types.js';
+import { formatTime } from "nrel-spa";
+import { getTimes } from "./getTimes.js";
+import type { FormattedPrayerTimes } from "./types.js";
 
 /**
  * Compute prayer times formatted as HH:MM:SS strings.

src/calcTimesAll.ts

@@ -2,9 +2,9 @@
  * Formatted prayer times — dynamic method plus all traditional method comparisons.
  */
 
-import { formatTime } from 'nrel-spa';
-import { getTimesAll } from './getTimesAll.js';
-import type { FormattedPrayerTimesAll } from './types.js';
+import { formatTime } from "nrel-spa";
+import { getTimesAll } from "./getTimesAll.js";
+import type { FormattedPrayerTimesAll } from "./types.js";
 
 /**
  * Compute prayer times formatted as HH:MM:SS strings, plus comparison times

src/getAngles.ts

@@ -50,10 +50,10 @@
  * - Jean Meeus, Astronomical Algorithms (2nd ed., 1998)
  */
 
-import { toJulianDate, solarEphemeris, atmosphericRefraction } from './getSolarEphemeris.js';
-import { getMscFajr, getMscIsha, minutesToDepression } from './getMSC.js';
-import { DEG, ANGLE_MIN, ANGLE_MAX } from './constants.js';
-import type { TwilightAngles } from './types.js';
+import { toJulianDate, solarEphemeris, atmosphericRefraction } from "./getSolarEphemeris.js";
+import { getMscFajr, getMscIsha, minutesToDepression } from "./getMSC.js";
+import { DEG, ANGLE_MIN, ANGLE_MAX } from "./constants.js";
+import type { TwilightAngles } from "./types.js";
 
 /** Internal result type including ephemeris data for caller reuse. */
 export interface AnglesWithEphemeris extends TwilightAngles {

src/getAsr.ts

@@ -7,7 +7,7 @@
  * and solar noon are known.
  */
 
-import { DEG } from './constants.js';
+import { DEG } from "./constants.js";
 
 /**
  * Compute Asr time as fractional hours.

src/getMSC.ts

@@ -22,7 +22,7 @@
  * High-latitude handling (|lat| > 55°): falls back to 1/7-night rule.
  */
 
-export type ShafaqMode = 'general' | 'ahmer' | 'abyad';
+export type ShafaqMode = "general" | "ahmer" | "abyad";
 
 /**
  * Normalisation latitude (degrees) used as the divisor in MCW latitude
@@ -130,21 +130,21 @@ export function getMscFajr(date: Date, latitude: number): number {
  * const offset = getMscIsha(new Date('2024-06-21'), 40.7128, 'general');
  * // offset ≈ 84
  */
-export function getMscIsha(date: Date, latitude: number, shafaq: ShafaqMode = 'general'): number {
+export function getMscIsha(date: Date, latitude: number, shafaq: ShafaqMode = "general"): number {
   const latAbs = Math.abs(latitude);
   const { dyy, daysInYear } = computeDyy(date, latitude);
 
   let a: number, b: number, c: number, d: number;
 
   switch (shafaq) {
-    case 'ahmer':
+    case "ahmer":
       // Shafaq ahmer (red glow): BASE = 62 min (shorter twilight)
       a = 62 + (17.4 / LAT_SCALE) * latAbs;
       b = 62 - (7.16 / LAT_SCALE) * latAbs;
       c = 62 + (5.12 / LAT_SCALE) * latAbs;
       d = 62 + (19.44 / LAT_SCALE) * latAbs;
       break;
-    case 'abyad':
+    case "abyad":
       // Shafaq abyad (white glow): BASE = 75 min (longer twilight)
       a = 75 + (25.6 / LAT_SCALE) * latAbs;
       b = 75 + (7.16 / LAT_SCALE) * latAbs;

src/getSolarEphemeris.ts

@@ -8,7 +8,7 @@
  * prayer time solving still uses the full SPA via nrel-spa.
  */
 
-import { DEG } from './constants.js';
+import { DEG } from "./constants.js";
 
 /**
  * Convert a JavaScript Date to a Julian Date number.

src/getTimes.ts

@@ -6,14 +6,14 @@
  * offset (tz parameter).
  */
 
-import { getSpa } from 'nrel-spa';
-import { computeAngles } from './getAngles.js';
-import { getAsr } from './getAsr.js';
-import { getQiyam } from './getQiyam.js';
-import { getMidnight } from './getMidnight.js';
-import { validateInputs } from './validate.js';
-import { DHUHR_OFFSET_MINUTES } from './constants.js';
-import type { PrayerTimes } from './types.js';
+import { getSpa } from "nrel-spa";
+import { computeAngles } from "./getAngles.js";
+import { getAsr } from "./getAsr.js";
+import { getQiyam } from "./getQiyam.js";
+import { getMidnight } from "./getMidnight.js";
+import { validateInputs } from "./validate.js";
+import { DHUHR_OFFSET_MINUTES } from "./constants.js";
+import type { PrayerTimes } from "./types.js";
 
 /**
  * Compute prayer times for a given date and location.

src/getTimesAll.ts

@@ -24,109 +24,109 @@
  * | MSC     | Moonsighting Committee Worldwide (seasonal)  | —     | —               | Global          |
  */
 
-import { getSpa } from 'nrel-spa';
-import { computeAngles } from './getAngles.js';
-import { getAsr } from './getAsr.js';
-import { getQiyam } from './getQiyam.js';
-import { getMidnight } from './getMidnight.js';
-import { getMscFajr, getMscIsha } from './getMSC.js';
-import { validateInputs } from './validate.js';
-import { DHUHR_OFFSET_MINUTES } from './constants.js';
-import type { MethodDefinition, PrayerTimesAll } from './types.js';
+import { getSpa } from "nrel-spa";
+import { computeAngles } from "./getAngles.js";
+import { getAsr } from "./getAsr.js";
+import { getQiyam } from "./getQiyam.js";
+import { getMidnight } from "./getMidnight.js";
+import { getMscFajr, getMscIsha } from "./getMSC.js";
+import { validateInputs } from "./validate.js";
+import { DHUHR_OFFSET_MINUTES } from "./constants.js";
+import type { MethodDefinition, PrayerTimesAll } from "./types.js";
 
 /** All supported traditional methods. */
 const METHODS: MethodDefinition[] = [
   {
-    id: 'UOIF',
-    name: 'Union des Organisations Islamiques de France',
-    region: 'France',
+    id: "UOIF",
+    name: "Union des Organisations Islamiques de France",
+    region: "France",
     fajrAngle: 12,
     ishaAngle: 12,
   },
   {
-    id: 'ISNACA',
-    name: 'IQNA / Islamic Council of North America',
-    region: 'Canada',
+    id: "ISNACA",
+    name: "IQNA / Islamic Council of North America",
+    region: "Canada",
     fajrAngle: 13,
     ishaAngle: 13,
   },
   {
-    id: 'ISNA',
-    name: 'FCNA / Islamic Society of North America',
-    region: 'US, UK, AU, NZ',
+    id: "ISNA",
+    name: "FCNA / Islamic Society of North America",
+    region: "US, UK, AU, NZ",
     fajrAngle: 15,
     ishaAngle: 15,
   },
   {
-    id: 'SAMR',
-    name: 'Spiritual Administration of Muslims of Russia',
-    region: 'Russia',
+    id: "SAMR",
+    name: "Spiritual Administration of Muslims of Russia",
+    region: "Russia",
     fajrAngle: 16,
     ishaAngle: 15,
   },
   {
-    id: 'IGUT',
-    name: 'Institute of Geophysics, University of Tehran',
-    region: 'Iran',
+    id: "IGUT",
+    name: "Institute of Geophysics, University of Tehran",
+    region: "Iran",
     fajrAngle: 17.7,
     ishaAngle: 14,
   },
-  { id: 'MWL', name: 'Muslim World League', region: 'Global', fajrAngle: 18, ishaAngle: 17 },
+  { id: "MWL", name: "Muslim World League", region: "Global", fajrAngle: 18, ishaAngle: 17 },
   {
-    id: 'DIBT',
-    name: 'Diyanet İşleri Başkanlığı, Turkey',
-    region: 'Turkey',
+    id: "DIBT",
+    name: "Diyanet İşleri Başkanlığı, Turkey",
+    region: "Turkey",
     fajrAngle: 18,
     ishaAngle: 17,
   },
   {
-    id: 'Karachi',
-    name: 'University of Islamic Sciences, Karachi',
-    region: 'PK, BD, IN, AF',
+    id: "Karachi",
+    name: "University of Islamic Sciences, Karachi",
+    region: "PK, BD, IN, AF",
     fajrAngle: 18,
     ishaAngle: 18,
   },
   {
-    id: 'Kuwait',
-    name: 'Kuwait Ministry of Islamic Affairs',
-    region: 'Kuwait',
+    id: "Kuwait",
+    name: "Kuwait Ministry of Islamic Affairs",
+    region: "Kuwait",
     fajrAngle: 18,
     ishaAngle: 17.5,
   },
   {
-    id: 'UAQ',
-    name: 'Umm Al-Qura University, Makkah',
-    region: 'Saudi Arabia',
+    id: "UAQ",
+    name: "Umm Al-Qura University, Makkah",
+    region: "Saudi Arabia",
     fajrAngle: 18.5,
     ishaAngle: null,
     ishaMinutes: 90,
   },
   {
-    id: 'Qatar',
-    name: 'Qatar / Gulf Standard',
-    region: 'Qatar, Gulf',
+    id: "Qatar",
+    name: "Qatar / Gulf Standard",
+    region: "Qatar, Gulf",
     fajrAngle: 18,
     ishaAngle: null,
     ishaMinutes: 90,
   },
   {
-    id: 'Egypt',
-    name: 'Egyptian General Authority of Survey',
-    region: 'EG, SY, IQ, LB',
+    id: "Egypt",
+    name: "Egyptian General Authority of Survey",
+    region: "EG, SY, IQ, LB",
     fajrAngle: 19.5,
     ishaAngle: 17.5,
   },
   {
-    id: 'MUIS',
-    name: 'Majlis Ugama Islam Singapura',
-    region: 'Singapore',
+    id: "MUIS",
+    name: "Majlis Ugama Islam Singapura",
+    region: "Singapore",
     fajrAngle: 20,
     ishaAngle: 18,
   },
   {
-    id: 'MSC',
-    name: 'Moonsighting Committee Worldwide',
-    region: 'Global',
+    id: "MSC",
+    name: "Moonsighting Committee Worldwide",
+    region: "Global",
     fajrAngle: null,
     ishaAngle: null,
     useMSC: true,

src/index.ts

@@ -16,17 +16,17 @@
  *   METHODS        - Array of all supported traditional method definitions
  */
 
-export { getTimes } from './getTimes.js';
-export { calcTimes } from './calcTimes.js';
-export { getTimesAll, METHODS } from './getTimesAll.js';
-export { calcTimesAll } from './calcTimesAll.js';
-export { getAngles } from './getAngles.js';
-export { getAsr } from './getAsr.js';
-export { getQiyam } from './getQiyam.js';
-export { getMidnight } from './getMidnight.js';
-export { getMscFajr, getMscIsha } from './getMSC.js';
-export { solarEphemeris, toJulianDate } from './getSolarEphemeris.js';
-export { DHUHR_OFFSET_MINUTES, ANGLE_MIN, ANGLE_MAX } from './constants.js';
+export { getTimes } from "./getTimes.js";
+export { calcTimes } from "./calcTimes.js";
+export { getTimesAll, METHODS } from "./getTimesAll.js";
+export { calcTimesAll } from "./calcTimesAll.js";
+export { getAngles } from "./getAngles.js";
+export { getAsr } from "./getAsr.js";
+export { getQiyam } from "./getQiyam.js";
+export { getMidnight } from "./getMidnight.js";
+export { getMscFajr, getMscIsha } from "./getMSC.js";
+export { solarEphemeris, toJulianDate } from "./getSolarEphemeris.js";
+export { DHUHR_OFFSET_MINUTES, ANGLE_MIN, ANGLE_MAX } from "./constants.js";
 
 export type {
   FractionalHours,
@@ -41,4 +41,15 @@ export type {
   FormattedPrayerTimesAll,
   AtmosphericParams,
   MethodDefinition,
-} from './types.js';
+} from "./types.js";
+
+// ── 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: 'pray-calc', version: '2.1.2' }),
+  )
+  .catch(() => {
+    // telemetry not installed or disabled — that is fine
+  });

src/types.ts

@@ -9,10 +9,10 @@ export type FractionalHours = number;
 export type TimeString = string;
 
 /** Asr shadow convention: Shafi'i (shadow = 1x object length) or Hanafi (2x). */
-export type AsrConvention = 'shafii' | 'hanafi';
+export type AsrConvention = "shafii" | "hanafi";
 
 /** Shafaq (twilight glow) variant for the MSC Isha model. */
-export type ShafaqMode = 'general' | 'ahmer' | 'abyad';
+export type ShafaqMode = "general" | "ahmer" | "abyad";
 
 /** Computed twilight depression angles for Fajr and Isha. */
 export interface TwilightAngles {