azaan-cli 1.0.0

package/README.md

@@ -0,0 +1,76 @@
+# Azaan CLI 🕌
+
+<p align="center">
+  <img src="./assets/icon.png" width="150" alt="Azaan CLI Logo" />
+</p>
+
+A lightweight, beautiful, and interactive CLI to check Azaan times anywhere in the world right from your terminal. Built for humans and status bars.
+
+![Azaan CLI Screenshot](./assets/image.png)
+
+## Install
+
+Install globally via npm:
+```bash
+npm install -g azaan-cli
+```
+
+## Usage
+
+On your first run, the CLI will interactively ask you for your City and Country, and save it in your config. 
+
+```bash
+azaan
+```
+
+**Override City (One-off):**
+If you want to quickly check another city without changing your configuration:
+```bash
+azaan "London"
+azaan "New York"
+```
+
+**Status Bar / Scripts (--status):**
+Output a single-line string of the next prayer and countdown. Perfect for tmux, Waybar, or Polybar.
+```bash
+azaan --status
+# Example Output: Next prayer is Maghrib in 45 mins and 12 seconds at 05:55 PM
+```
+
+**Configure & Reset:**
+To change your default saved city or calculation method later:
+```bash
+azaan config
+```
+To completely clear your local configuration:
+```bash
+azaan reset
+```
+
+## Desktop Notifications (Zero Setup)
+
+The `azaan-cli` comes with a built-in lightweight background daemon for notifications. **There is zero setup required.**
+
+![Azaan Notification Example](./assets/Notification.png)
+
+The moment you run `azaan` in your terminal, the background process starts automatically. It will quietly check the time in the background and send you a native desktop notification **10 minutes before** every Azaan, and exactly **at the time** of the Azaan.
+
+### Managing the Daemon
+You don't need to do anything to start it, but if you want manual control, you can use the daemon commands:
+```bash
+# Check if the daemon is running
+azaan daemon status
+
+# Stop the background notifications
+azaan daemon stop
+
+# Start the daemon manually
+azaan daemon start
+```
+
+## Shoutout 🙌
+A massive thank you and shoutout to [Ahmad Awais](https://github.com/AhmadAwais) for building [ramadan-cli](https://github.com/AhmadAwais/ramadan-cli), which served as the primary inspiration and foundation that led to the creation of Azaan CLI. 
+
+## Powered By
+- [Aladhan Prayer Times API](https://aladhan.com/prayer-times-api)
+- `commander` & `@clack/prompts`

package/bin/azaan.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli.js';
+
+runCli().catch((err) => {
+  console.error('\nAn unexpected error occurred:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "azaan-cli",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "azaan": "./bin/azaan.js"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "azaan",
+    "prayer",
+    "islam",
+    "muslim",
+    "salah",
+    "namaz",
+    "adhan",
+    "cli"
+  ],
+  "author": "Hamza Rasheed",
+  "license": "ISC",
+  "description": "A lightweight, beautiful, and interactive CLI to check Azaan times anywhere in the world.",
+  "dependencies": {
+    "@clack/prompts": "^1.0.1",
+    "axios": "^1.13.5",
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.3",
+    "conf": "^15.1.0",
+    "date-fns": "^4.1.0",
+    "node-notifier": "^10.0.1"
+  }
+}

package/src/api.js

@@ -0,0 +1,38 @@
+import axios from 'axios';
+
+const ALADHAN_BASE_URL = 'http://api.aladhan.com/v1';
+
+/**
+ * Fetches prayer timings for a given date.
+ * If date is not provided, defaults to today.
+ *
+ * @param {string} city
+ * @param {string} country
+ * @param {number} method - Calculation method
+ * @param {string} [date] - DD-MM-YYYY format
+ */
+export async function fetchTimings(city, country, method = 2, date = null) {
+    try {
+        const endpoint = date
+            ? `${ALADHAN_BASE_URL}/timingsByCity/${date}`
+            : `${ALADHAN_BASE_URL}/timingsByCity`;
+
+        const params = {
+            city,
+            country,
+            method,
+        };
+
+        const response = await axios.get(endpoint, { params });
+        if (response.data && response.data.code === 200) {
+            return response.data;
+        } else {
+            throw new Error('Invalid response from Aladhan API');
+        }
+    } catch (error) {
+        if (error.response && error.response.data && error.response.data.data) {
+            throw new Error(`API Error: ${error.response.data.data}`);
+        }
+        throw new Error(`Failed to fetch timings: ${error.message}`);
+    }
+}

package/src/cli.js

@@ -0,0 +1,161 @@
+import { Command } from 'commander';
+import { getConfig, setConfig, clearConfig, getDaemonPid, setDaemonPid } from './config.js';
+import { runInteractiveSetup, printTimingsTable, createSpinner } from './ui.js';
+import { fetchTimings } from './api.js';
+import { getNextPrayer, formatCountdown, formatCountdownVerbose, formatTime12h } from './utils.js';
+import chalk from 'chalk';
+import notifier from 'node-notifier';
+import { format } from 'date-fns';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { spawn } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function isDaemonRunning(pid) {
+    if (!pid) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+function startDaemonIfNeeded() {
+    const pid = getDaemonPid();
+    if (isDaemonRunning(pid)) return;
+
+    const daemonPath = join(__dirname, 'daemon.js');
+    const child = spawn(process.execPath, [daemonPath], {
+        detached: true,
+        stdio: 'ignore'
+    });
+
+    child.unref();
+    if (child.pid) setDaemonPid(child.pid);
+}
+
+export async function runCli() {
+    const program = new Command();
+
+    program
+        .name('azaan')
+        .description('CLI to check Azaan times anywhere in the world.')
+        .version('1.0.0');
+
+    program
+        .argument('[city]', 'City to check timings for (one-off)')
+        .option('-s, --status', 'Print single-line next prayer status')
+        .action(async (cmdCity, options) => {
+            let config = getConfig();
+
+            // If no config and no arguments, ask for setup unless it's a status check
+            if (!config.city && !cmdCity && !options.status) {
+                config = await runInteractiveSetup({});
+                setConfig(config);
+            }
+
+            const city = cmdCity || config.city;
+            const country = config.country || '';
+            const method = config.method || 2;
+
+            if (!city) {
+                console.error(chalk.red('City not configured. Run "azaan config" or provide a city parameter.'));
+                process.exit(1);
+            }
+
+            // Auto start daemon
+            startDaemonIfNeeded();
+
+            let s;
+            if (!options.status) s = createSpinner(`Fetching azaan times for ${city}...`);
+
+            try {
+                const dateStr = format(new Date(), 'dd-MM-yyyy');
+                // Actually fetch Timings by City from Aladhan wrapper
+                const data = await fetchTimings(city, country, method, dateStr);
+                let todayTimings = null;
+
+                // Find today's data (if array, pick first, usually it's single object for "timingsByCity/date")
+                if (data && data.data && data.data.timings) {
+                    todayTimings = data.data.timings;
+                }
+
+                if (s) s.stop('Times fetched successfully.');
+
+                if (!todayTimings) {
+                    throw new Error('Timings not found in response');
+                }
+
+                if (options.status) {
+                    const next = getNextPrayer(todayTimings);
+                    if (next) {
+                        console.log(`Next prayer is ${next.name} in ${formatCountdownVerbose(next.diffSeconds)} at ${formatTime12h(next.time)}`);
+                        process.exit(0);
+                    } else {
+                        console.log('No more prayers today.');
+                        process.exit(0);
+                    }
+                }
+
+                printTimingsTable(todayTimings, city);
+
+            } catch (err) {
+                if (s) s.stop('Failed to fetch data.', 1);
+                console.error(chalk.red('\nError: ' + err.message));
+                process.exit(1);
+            }
+        });
+
+    program
+        .command('config')
+        .description('Configure default settings')
+        .action(async () => {
+            const config = getConfig();
+            const newConfig = await runInteractiveSetup(config);
+            setConfig(newConfig);
+        });
+
+    program
+        .command('reset')
+        .description('Clear saved settings')
+        .action(() => {
+            clearConfig();
+            console.log(chalk.green('Configuration cleared successfully.'));
+        });
+
+    program
+        .command('daemon [action]')
+        .description('Manage the background notification daemon (start/stop/status)')
+        .action((action) => {
+            const pid = getDaemonPid();
+            if (action === 'stop') {
+                if (isDaemonRunning(pid)) {
+                    try {
+                        process.kill(pid);
+                    } catch (e) { }
+                    console.log(chalk.green('Daemon stopped.'));
+                } else {
+                    console.log(chalk.yellow('Daemon is not running.'));
+                }
+                setDaemonPid(null);
+            } else if (action === 'start') {
+                if (isDaemonRunning(pid)) {
+                    console.log(chalk.yellow('Daemon is already running.'));
+                } else {
+                    startDaemonIfNeeded();
+                    console.log(chalk.green('Daemon started successfully! You will receive notifications in the background.'));
+                }
+            } else {
+                if (isDaemonRunning(pid)) {
+                    console.log(chalk.green(`Daemon is running in the background (PID: ${pid}).`));
+                } else {
+                    console.log(chalk.yellow('Daemon is not running.'));
+                }
+            }
+        });
+
+    await program.parseAsync(process.argv);
+}

package/src/config.js

@@ -0,0 +1,41 @@
+import Conf from 'conf';
+
+// Initialize a new config instance specific to azaan-cli
+const config = new Conf({
+    projectName: 'azaan-cli',
+    defaults: {
+        city: null,
+        country: null,
+        method: 2, // ISNA is method 2 in Aladhan API
+        school: 0, // Shafi by default
+        daemonPid: null, // Store PID of the detached daemon
+    }
+});
+
+export function getConfig() {
+    return {
+        city: config.get('city'),
+        country: config.get('country'),
+        method: config.get('method'),
+        school: config.get('school'),
+    };
+}
+
+export function setConfig(newConfig) {
+    if (newConfig.city) config.set('city', newConfig.city);
+    if (newConfig.country) config.set('country', newConfig.country);
+    if (newConfig.method !== undefined) config.set('method', newConfig.method);
+    if (newConfig.school !== undefined) config.set('school', newConfig.school);
+}
+
+export function getDaemonPid() {
+    return config.get('daemonPid');
+}
+
+export function setDaemonPid(pid) {
+    config.set('daemonPid', pid);
+}
+
+export function clearConfig() {
+    config.clear();
+}

package/src/daemon.js

@@ -0,0 +1,71 @@
+import { getConfig } from './config.js';
+import { fetchTimings } from './api.js';
+import { getNextPrayer, formatTime12h } from './utils.js';
+import notifier from 'node-notifier';
+import { format } from 'date-fns';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const ICON_PATH = join(__dirname, '../assets/icon.png');
+
+// 60 seconds interval
+const INTERVAL_MS = 60 * 1000;
+
+// Poll loop
+async function runDaemon() {
+    const config = getConfig();
+    if (!config.city) return;
+
+    try {
+        const dateStr = format(new Date(), 'dd-MM-yyyy');
+        const data = await fetchTimings(config.city, config.country || '', config.method || 2, dateStr);
+        const timings = data?.data?.timings;
+
+        if (!timings) return;
+
+        const next = getNextPrayer(timings);
+        if (next) {
+            // Send notification exactly 10 minutes beforehand.
+            // Since interval is 60s, diffSeconds will be between 540 and 600 seconds.
+            // To ensure we report exactly once, keep track of the reported prayer.
+            // Since it's a daemon that could be restarted, checking the time diff is safer.
+            const diffMins = next.diffSeconds / 60;
+
+            // If diff is between 9 and 10 minutes
+            if (diffMins > 9 && diffMins <= 10) {
+                const minutes = Math.ceil(diffMins);
+
+                notifier.notify({
+                    appID: 'Azaan CLI',
+                    icon: ICON_PATH,
+                    title: `Azaan Reminder: ${next.name}`,
+                    message: `${next.name} is starting in ${minutes} minutes at ${formatTime12h(next.time)}!`,
+                    sound: true,
+                    wait: false
+                });
+            }
+
+            // If diff is exactly 0 (between 0 and 1 min)
+            if (diffMins > 0 && diffMins <= 1) {
+                notifier.notify({
+                    appID: 'Azaan CLI',
+                    icon: ICON_PATH,
+                    title: `Azaan Time: ${next.name}`,
+                    message: `It is now time for ${next.name} (${formatTime12h(next.time)}).`,
+                    sound: true,
+                    wait: false
+                });
+            }
+        }
+    } catch (err) {
+        // Fail silently in background
+    }
+}
+
+// Initial run
+runDaemon();
+
+// Start polling
+setInterval(runDaemon, INTERVAL_MS);

package/src/ui.js

@@ -0,0 +1,122 @@
+import { intro, text, select, spinner, isCancel, cancel, outro } from '@clack/prompts';
+import chalk from 'chalk';
+import Table from 'cli-table3';
+import { formatTime12h, getNextPrayer, formatCountdownVerbose } from './utils.js';
+
+export async function runInteractiveSetup(currentConfig = {}) {
+    intro(chalk.bgGreen.white(' Azaan CLI Setup '));
+
+    const city = await text({
+        message: 'Which city are you in?',
+        placeholder: 'e.g. Lahore, London, New York',
+        initialValue: currentConfig.city || '',
+        validate(value) {
+            if (value.length === 0) return `City is required!`;
+        },
+    });
+
+    if (isCancel(city)) {
+        cancel('Setup cancelled.');
+        process.exit(0);
+    }
+
+    const country = await text({
+        message: 'Which country?',
+        placeholder: 'e.g. Pakistan, UK, US',
+        initialValue: currentConfig.country || '',
+        validate(value) {
+            if (value.length === 0) return `Country is required!`;
+        },
+    });
+
+    if (isCancel(country)) {
+        cancel('Setup cancelled.');
+        process.exit(0);
+    }
+
+    const method = await select({
+        message: 'Calculation Method',
+        options: [
+            { value: 1, label: 'University of Islamic Sciences, Karachi' },
+            { value: 2, label: 'Islamic Society of North America (ISNA)' },
+            { value: 3, label: 'Muslim World League' },
+            { value: 4, label: 'Umm Al-Qura University, Makkah' },
+            { value: 5, label: 'Egyptian General Authority of Survey' },
+            { value: 8, label: 'Gulf Region' },
+            { value: 9, label: 'Kuwait' },
+            { value: 10, label: 'Qatar' },
+            { value: 11, label: 'Majlis Ugama Islam Singapura, Singapore' },
+            { value: 12, label: 'Union Organization islamic de France' },
+            { value: 13, label: 'Diyanet İşleri Başkanlığı, Turkey' },
+            { value: 14, label: 'Spiritual Administration of Muslims of Russia' }
+        ],
+        initialValue: currentConfig.method || 2,
+    });
+
+    if (isCancel(method)) {
+        cancel('Setup cancelled.');
+        process.exit(0);
+    }
+
+    outro('Setup complete! Configuration saved.');
+
+    return { city, country, method };
+}
+
+export function printTimingsTable(timingsObj, city) {
+    console.log(chalk.cyan(`
+  █████╗ ███████╗ █████╗  █████╗ ███╗   ██╗
+ ██╔══██╗╚══███╔╝██╔══██╗██╔══██╗████╗  ██║
+ ███████║  ███╔╝ ███████║███████║██╔██╗ ██║
+ ██╔══██║ ███╔╝  ██╔══██║██╔══██║██║╚██╗██║
+ ██║  ██║███████╗██║  ██║██║  ██║██║ ╚████║
+ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝
+`));
+    console.log(`  🕌 ${chalk.bold('Daily Prayer Timings')}`);
+    console.log(`  📍 ${chalk.green.bold(city)} (${chalk.gray('Today')})\n`);
+
+    const table = new Table({
+        head: [chalk.bold.blue('Prayer'), chalk.bold.blue('Time')],
+        colWidths: [20, 20],
+        chars: {
+            'top': '', 'top-mid': '', 'top-left': '', 'top-right': '',
+            'bottom': '', 'bottom-mid': '', 'bottom-left': '', 'bottom-right': '',
+            'left': '  ', 'left-mid': '', 'mid': '', 'mid-mid': '',
+            'right': '', 'right-mid': '', 'middle': '   '
+        },
+        style: { 'padding-left': 0, 'padding-right': 0, head: [], border: [] }
+    });
+
+    const nextPrayer = getNextPrayer(timingsObj);
+    const prayers = ['Fajr', 'Dhuhr', 'Asr', 'Maghrib', 'Isha'];
+
+    prayers.forEach((prayer) => {
+        if (timingsObj[prayer]) {
+            // Remove timezone string like "(EST)"
+            const rawTime = timingsObj[prayer].split(' ')[0];
+            const time12h = formatTime12h(rawTime);
+
+            let pName = prayer;
+            let pTime = time12h;
+
+            if (nextPrayer && nextPrayer.name === prayer) {
+                pName = chalk.bgYellow.black(` ${prayer} (Next) `);
+                pTime = chalk.yellow.bold(time12h);
+            }
+
+            table.push([pName, pTime]);
+        }
+    });
+
+    console.log(table.toString());
+
+    if (nextPrayer) {
+        console.log(`\n  Next prayer is ${chalk.bold.yellow(nextPrayer.name)} in ${chalk.bold.cyan(formatCountdownVerbose(nextPrayer.diffSeconds))} at ${chalk.bold.magenta(formatTime12h(nextPrayer.time))}\n`);
+    }
+}
+
+export function createSpinner(msg) {
+    const s = spinner();
+    s.start(msg);
+    return s;
+}

package/src/utils.js

@@ -0,0 +1,90 @@
+import { parse, format, differenceInSeconds, isAfter, isBefore } from 'date-fns';
+
+/**
+ * Converts HH:mm (24-hour) format into a 12-hour AM/PM string.
+ */
+export function formatTime12h(time24) {
+    const [hours, minutes] = time24.split(':');
+    const d = new Date();
+    d.setHours(parseInt(hours, 10), parseInt(minutes, 10));
+    return format(d, 'hh:mm a');
+}
+
+/**
+ * Given a list of timings from Aladhan API, find the next prayer.
+ * Returns { name, time, diffSeconds } or null.
+ */
+export function getNextPrayer(timingsObj) {
+    const now = new Date();
+
+    // The prayers we care about
+    const prayers = ['Fajr', 'Dhuhr', 'Asr', 'Maghrib', 'Isha'];
+
+    let nextPrayer = null;
+    let minDiff = Infinity;
+
+    // Clean the timings (Aladhan sometimes appends (PKT) etc)
+    for (const prayer of prayers) {
+        if (!timingsObj[prayer]) continue;
+
+        const timeStr = timingsObj[prayer].split(' ')[0]; // removes " (EST)"
+        const [hours, minutes] = timeStr.split(':');
+
+        const prayerTime = new Date();
+        prayerTime.setHours(parseInt(hours, 10), parseInt(minutes, 10), 0, 0);
+
+        if (isAfter(prayerTime, now)) {
+            const diffSecs = differenceInSeconds(prayerTime, now);
+            if (diffSecs < minDiff) {
+                minDiff = diffSecs;
+                nextPrayer = {
+                    name: prayer,
+                    time: timeStr,
+                    diffSeconds: diffSecs,
+                    dateObj: prayerTime
+                };
+            }
+        }
+    }
+
+    // If no next prayer today, the next is Fajr tomorrow
+    // (We'll handle tomorrow Fajr logic loosely by just saying "Tomorrow's Fajr" or leaving null)
+    return nextPrayer;
+}
+
+/**
+ * Format seconds into HH:MM:SS
+ */
+export function formatCountdown(totalSeconds) {
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+
+    const pad = (num) => String(num).padStart(2, '0');
+
+    if (hours > 0) {
+        return `${pad(hours)}:${pad(minutes)}:${pad(seconds)}`;
+    }
+    return `${pad(minutes)}:${pad(seconds)}`;
+}
+
+/**
+ * Format seconds into verbose text (e.g. 45 min and 12 second)
+ */
+export function formatCountdownVerbose(totalSeconds) {
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = totalSeconds % 60;
+
+    let parts = [];
+    if (hours > 0) parts.push(`${hours} hr${hours > 1 ? 's' : ''}`);
+    if (minutes > 0) parts.push(`${minutes} min${minutes > 1 ? 's' : ''}`);
+    if (seconds > 0) parts.push(`${seconds} second${seconds > 1 ? 's' : ''}`);
+
+    if (parts.length === 0) return 'now';
+    if (parts.length === 1) return parts[0];
+    if (parts.length === 2) return `${parts[0]} and ${parts[1]}`;
+
+    const last = parts.pop();
+    return `${parts.join(', ')} and ${last}`;
+}