Metadata-Version: 2.4
Name: keka-log
Version: 0.1.0
Summary: CLI and optional macOS menu bar app for Keka attendance tracking.
Author: Quid Keka Log contributors
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/keka-log/
Keywords: keka,attendance,time-tracking,macos,menubar
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: menubar
Requires-Dist: rumps>=0.4.0; extra == "menubar"
Dynamic: license-file

# Keka Log

A Python package for checking and tracking Keka attendance. Includes a CLI tool and a Mac menu bar app to keep track of your shift time.

## Prerequisites & Configuration (`.zshrc`)

Before using this tool, you need to extract your `KEKA_TOKEN` from your browser and configure it in your shell.

### 1. Get your Keka Token
1. Log in to your Keka portal in your web browser.
2. Open Developer Tools (Inspect Element) -> **Network** tab.
3. Refresh the page or navigate to the attendance section.
4. Look for an API request (e.g., `summary` or `attendance`).
5. Check the **Request Headers** for the `Authorization` header. It will look like `Bearer eyJ...`.
6. Copy the long token string (everything after `Bearer `).

### 2. Add to your `.zshrc`
You need to configure the token and your preferred notification language in your shell configuration file (e.g., `~/.zshrc`).

1. Open your `.zshrc` file in your terminal:
   ```bash
   nano ~/.zshrc
   ```
2. Add the following lines at the bottom of the file:
   ```bash
   # Keka Attendance App Configuration
   export KEKA_TOKEN="paste_your_copied_token_here"
   
   # Optional: Set notification audio language ('hindi', 'telugu', or 'none')
   # Defaults to 'hindi' if not set. Use 'none' to disable audio entirely.
   export KEKA_LANGUAGE="telugu"
   ```
3. Save the file (in nano: `Ctrl+O`, `Enter`, `Ctrl+X`) and reload your configuration:
   ```bash
   source ~/.zshrc
   ```

## Installation

### From PyPI (recommended)

Install the CLI from [PyPI](https://pypi.org/project/keka-log/) (replace the version if you pin one):

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install keka-log
```

On **macOS**, install with the `menubar` extra so `keka-menubar` works (pulls in `rumps` and its dependencies):

```bash
pip install keka-log[menubar]
```

The base package has no third-party dependencies; only `keka-log[menubar]` adds the menu bar stack.

### Without a virtual environment (direct install)

Yes — you can install **normally** with `pip` into your user account or system Python, no `.venv` required.

**CLI only:**

```bash
pip3 install keka-log
```

**macOS menu bar as well:**

```bash
pip3 install "keka-log[menubar]"
```

On **macOS with Homebrew Python** (and some Linux distros), plain `pip install` may be blocked with *externally-managed-environment*. In that case install into your user site-packages instead:

```bash
pip3 install --user "keka-log[menubar]"
```

Make sure your shell can find the scripts. User installs usually put executables under `~/.local/bin`. If `keka-log` is not found, add this to `~/.zshrc` and open a new terminal:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

**Alternative — isolated apps without managing a venv yourself:** use [pipx](https://pypa.github.io/pipx/) (install with `brew install pipx` on macOS, then `pipx ensurepath`):

```bash
pipx install "keka-log[menubar]"
```

That installs the package in its own environment and puts `keka-log` / `keka-menubar` on your `PATH`.

### From a local clone

With a venv (good for development):

```bash
cd path/to/quid-keka-log
python3 -m venv .venv
source .venv/bin/activate
pip install ".[menubar]"   # macOS: CLI + menubar
# or
pip install .              # CLI only (no rumps)
```

Or install directly from the folder without a venv:

```bash
cd path/to/quid-keka-log
pip3 install --user ".[menubar]"
```

If you use a venv, run `source .venv/bin/activate` in each new terminal session where you want those commands.

### Publishing a new release (maintainers)

1. Bump `version` in `pyproject.toml` (and optionally `keka_log/__init__.py`).
2. Build and upload to PyPI (use [API tokens](https://pypi.org/manage/account/token/), not your password):

```bash
pip install build twine
python -m build
twine upload dist/*
```

For TestPyPI first:

```bash
twine upload --repository testpypi dist/*
```

Then install with:

```bash
pip install -i https://test.pypi.org/simple/ keka-log
```

## Usage

If you installed inside a **virtual environment**, activate it first:

```bash
source .venv/bin/activate
```

If you installed with **`pip install --user`**, **`pipx`**, or a **system** `pip3 install`, you do not need a venv — open a normal terminal (ensure `~/.local/bin` is on your `PATH` if you used `--user`).

### Run and stop commands

| What | Run | Stop |
|------|-----|------|
| **CLI** (one-shot print) | `keka-log` | Nothing to stop — it exits after printing. |
| **CLI** (refresh cache) | `keka-log refresh` | Same — exits when done. |
| **Menu bar app** (stays running) | `keka-menubar` | See **Stopping the menu bar app** below. |

**Stopping the menu bar app** (`keka-menubar` keeps running until you quit):

1. **From the menu bar (recommended):** Click the Keka item in the top-right menu bar → **Quit**.
2. **If you started it in a terminal** and that window is still open: focus that terminal and press **Ctrl+C**.
3. **From another terminal** (if you closed the window or need to force-quit):

   ```bash
   pkill -f keka-menubar
   ```

   If nothing matches, list Python processes and stop the one running the app:

   ```bash
   ps aux | grep -i keka
   kill <PID>
   ```

   Replace `<PID>` with the process id from the `ps` output.

---

### 1. CLI tool

Print current attendance info, effective hours, and optimistic logout time:

```bash
keka-log
```

Refresh cached data from the Keka server:

```bash
keka-log refresh
```

### 2. Mac menu bar app (requires `pip install keka-log[menubar]`)

Start the live countdown in the macOS menu bar:

```bash
keka-menubar
```

This shows a timer in the menu bar. When your shift is complete, it can play audio (unless `KEKA_LANGUAGE=none`) and show a notification. Use **Quit** in the menu or the stop commands above when you are done for the day.
