initial commit

2026-10-01 11:53:34 -04:00
commit 90f6666986
@@ -0,0 +1,252 @@
+# 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