# yourls-ui

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 (v0.1)

- System tray application
- Simple configuration window
- Uses YOURLS API with **signature authentication**
- Reads URL from clipboard
- Generates a short URL
- Copies the short URL back to clipboard
- Shows popup with clickable link
- Error reporting with API response

---

# 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. Copy the shortened link back to clipboard
6. Show a popup window with the result

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
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
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
```

The YOURLS API communication is encapsulated in `YourlsClient`.

---

# 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://example.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

```
v0.1
```

Initial working release.

---

# Author

```
deeaitch
```

---

# License

GPL