yourls-ui/README.md

# yourls-ui 1.0

Small Qt tray utility for shortening URLs using the **YOURLS API**.

The application sits in the system tray and allows quickly shortening the URL currently stored in the clipboard.

It was designed as a lightweight helper for everyday use with a self-hosted YOURLS instance.

---

# Features (v1.0)

- System tray application
- Simple configuration window
- Uses YOURLS API with **signature authentication**
- Reads URL from clipboard
- Accepts plain URLs, quoted URLs, Markdown links and browser URL MIME data
- Generates a short URL
- Reuses existing short links returned by YOURLS for duplicate URLs
- Copies the short URL back to clipboard
- Supports Wayland clipboard access through focused dialogs and verifies copying
- Shows popup with clickable link
- Error reporting with API response
- Debug-only diagnostics for clipboard and API troubleshooting

---

# How it works

1. Application starts
2. If configuration exists → it goes directly to the **system tray**
3. If configuration is missing → **settings window opens**

From the tray menu you can run:

```
Cut URL
```

The application will:

1. Read the current clipboard
2. Check if the content is a valid URL
3. Call the YOURLS API
4. Receive a shortened link
5. Show a popup window with the result
6. Copy the shortened link back to clipboard and verify the copy

If YOURLS returns HTTP 400 with `error:url` and an existing short link for
the same source URL, the application uses that link as a successful result.

On Wayland, `Cut URL` opens a small window when the application is inactive.
Activate it to allow clipboard access; the URL is read automatically once
the clipboard becomes available. You can also click `Read clipboard`, or cancel.
The result window copies the short URL after gaining focus and displays whether
the copy succeeded. Clicking `OK` retries and verifies the copy before closing.

---

# Configuration

The settings window contains:

```
API URL
API signature
```

Example:

```
API URL:
https://example.com/yourls-api.php

Signature:
ABC123
```

⚠️ Important:

The signature field must contain **only the signature value**, not:

```
signature=ABC123
```

Correct:

```
ABC123
```

---

# Tray menu

Right click the tray icon to access the menu:

```
Cut URL
Settings
Help
About
Exit
```

Double clicking the tray icon opens the settings window.

---

# Building

Requirements:

```
Qt 6
Qt Widgets
Qt Network
qmake from Qt 6 (qmake6 on this system)
C++17 compiler
```

Build:

```bash
mkdir -p build-qt6
cd build-qt6
qmake6 ../yourls-ui.pro CONFIG+=release CONFIG-=debug
make
```

The Qt 6 qmake executable may be named `qmake` on other systems; check its
version with `qmake -v` before building.

Or open `yourls-ui.pro` in **Qt Creator**, select a Qt 6 kit and use a new
build directory separate from any existing Qt 5 build.

---

# Debugging clipboard URLs

Build and run a debug executable from a terminal:

```bash
mkdir -p build/Desktop-Debug
cd build/Desktop-Debug
qmake6 ../../yourls-ui.pro CONFIG+=debug CONFIG-=release
make
./yourls-ui 2>clipboard-debug.log
```

Exit any already running instance before starting this executable. Choose
`Cut URL` and inspect `clipboard-debug.log`. Debug builds log the executable
path, Qt platform, clipboard MIME formats, raw text and its UTF-8 hex bytes,
parsed URL, request stage, HTTP status and API status. The API signature and
full request query are not logged. Clipboard diagnostics may contain private
URLs; review the log before sharing it. These diagnostics are compiled out of
release builds using `QT_NO_DEBUG`.

---

# Project structure

```
main.cpp
    Application entry point

mainwindow.h / mainwindow.cpp
    Main application window
    Tray integration
    UI logic

mainwindow.ui
    Qt Designer UI for settings window

yourlsclient.h / yourlsclient.cpp
    YOURLS API client
    Handles HTTP requests and responses

clipboardurl.h
    Clipboard MIME data and URL text parsing

clipboardresultdialog.h
    Focus-aware clipboard writing and copy verification

tests/
    Standalone qmake projects for automated tests
```

The YOURLS API communication is encapsulated in `YourlsClient`.

---

# Tests

The `tests/` directory contains three independent test executables:

| Test | Coverage |
| --- | --- |
| `clipboardurl_test` | Plain, quoted and Markdown URLs; browser MIME URLs; query strings, fragments and parentheses; invalid or empty input. |
| `yourlsclient_test` | HTTP 200 success, HTTP 400 duplicate reuse, rejection of mismatched or invalid links, other API errors and HTTP 500; URL encoding in requests. |
| `clipboardresultdialog_test` | No clipboard overwrite before focus, automatic copying on activation, copy verification and retry, and copying on platforms without the focus requirement. |

Tests require Qt 6 and a C++17 compiler. The API and dialog tests also require
the **Qt Test** module; the dialog test uses Qt Widgets and the API test uses
Qt Network.

Run the following from the repository root. Each subshell builds and runs one
test in its own directory:

```bash
mkdir -p build/tests/clipboardurl build/tests/yourlsclient build/tests/clipboardresultdialog

(
  cd build/tests/clipboardurl &&
  qmake6 ../../../tests/clipboardurl_test.pro &&
  make &&
  ./clipboardurl_test
)

(
  cd build/tests/yourlsclient &&
  qmake6 ../../../tests/yourlsclient_test.pro &&
  make &&
  ./yourlsclient_test
)

(
  cd build/tests/clipboardresultdialog &&
  qmake6 ../../../tests/clipboardresultdialog_test.pro &&
  make &&
  QT_QPA_PLATFORM=offscreen ./clipboardresultdialog_test
)
```

The API test starts a local HTTP server and requires permission to bind a
loopback port. It uses a test signature and does not contact a real YOURLS
instance. The dialog test uses Qt's `offscreen` platform for automated checks;
it does not verify a real Wayland compositor.

For a manual Wayland check, copy a URL in another application, choose `Cut URL`,
activate the clipboard dialog, then activate the result window. Confirm that
it reports a successful copy, close it with `OK`, and paste into another
application. Repeat with the same URL to verify reuse of the existing short
link. Debug builds additionally report `verified: true` for a successful
clipboard write.

---

# API call

The application performs a request similar to:

```
GET /yourls-api.php
?action=shorturl
&format=json
&signature=<signature>
&url=<url>
```

Example:

```
https://example.com/yourls-api.php?action=shorturl&format=json&signature=ABC123&url=https%3A%2F%2Fexample.com
```

---

# Future ideas

Possible improvements for future versions:

### Hotkey support
Global hotkey to trigger URL shortening.

### Clipboard watcher
Automatically detect URLs copied to clipboard.

### Tray notifications
Use system notifications instead of popup dialog.

### Recent history
Store last shortened URLs.

### Custom alias
Allow specifying custom short URL alias.

### Open YOURLS admin
Add tray menu entry for opening YOURLS admin panel.

### Packaging
Provide:

```
AppImage
.deb package
```

---

# Version

```
v1.0
```

Stable release with Wayland clipboard support, verified short URL copying,
reuse of existing YOURLS links, automated regression tests and debug diagnostics.

---

# Author

```
deeaitch
```

---

# License

GPL