From d7a336e524c007ca3153f3b9e081254e34458fe2 Mon Sep 17 00:00:00 2001 From: vesp Date: Mon, 12 Jan 2026 23:50:36 +0100 Subject: [PATCH] Update README.md with wiki links --- README.md | 234 +++++++++++++++++++----------------------------------- 1 file changed, 82 insertions(+), 152 deletions(-) diff --git a/README.md b/README.md index 0701c2f..c955719 100644 --- a/README.md +++ b/README.md @@ -6,187 +6,117 @@ A modern HTTP client for GNOME, built with GTK 4 and libadwaita. - Send HTTP requests (GET, POST, PUT, DELETE) - Configure custom headers and request bodies -- View response headers and bodies +- View response headers and bodies with syntax highlighting - Track request history with persistence -- **JavaScript preprocessing and postprocessing scripts** -- **Project environments with variables** +- Organize requests into projects +- Environment variables with secure credential storage +- JavaScript preprocessing and postprocessing scripts +- Export requests (cURL and more) - Beautiful GNOME-native UI -## Dependencies +## Quick Start -- GTK 4 -- libadwaita 1 -- Python 3 -- libsoup3 (provided by GNOME Platform) -- gjs (GNOME JavaScript) - for script execution - -## Building +### Installation +**Build from source:** ```bash +git clone https://git.bugsy.cz/beval/roster.git +cd roster meson setup builddir meson compile -C builddir sudo meson install -C builddir ``` -## Usage - -Roster uses libsoup3 (from GNOME Platform) for making HTTP requests - no external dependencies required. - -Run Roster from your application menu or with the `roster` command. - -## Scripts - -Roster supports JavaScript preprocessing and postprocessing scripts to automate request modifications and response data extraction. - -### Preprocessing Scripts - -**Run BEFORE the HTTP request is sent.** Use preprocessing to: -- Modify request headers, URL, body, or method -- Add dynamic values (timestamps, request IDs, signatures) -- Read environment variables -- Set/update environment variables - -**Available API:** -```javascript -// Request object (modifiable) -request.method // "GET", "POST", "PUT", "DELETE" -request.url // Full URL string -request.headers // Object with header key-value pairs -request.body // Request body string - -// Roster API -roster.getVariable(name) // Get variable from selected environment -roster.setVariable(name, value) // Set/update variable -roster.setVariables({key: value}) // Batch set variables -roster.project.name // Current project name -roster.project.environments // Array of environment names - -// Console output -console.log(message) // Output shown in preprocessing results +**Flatpak:** +```bash +flatpak-builder --user --install --force-clean build-dir cz.bugsy.roster.json +flatpak run cz.bugsy.roster ``` -**Example 1: Add Dynamic Authentication Header** -```javascript -const token = roster.getVariable('auth_token'); -request.headers['Authorization'] = 'Bearer ' + token; -request.headers['X-Request-Time'] = new Date().toISOString(); -console.log('Added auth header for token:', token); -``` +See the [Installation Guide](https://git.bugsy.cz/beval/roster/wiki/Installation) for detailed instructions. -**Example 2: Modify Request Based on Environment** -```javascript -const env = roster.getVariable('environment_name'); -if (env === 'production') { - request.url = request.url.replace('localhost', 'api.example.com'); - console.log('Switched to production URL'); -} -``` +### Usage -**Example 3: Generate Request Signature** -```javascript -const apiKey = roster.getVariable('api_key'); -const timestamp = Date.now().toString(); -const requestId = Math.random().toString(36).substring(7); +Launch Roster from your application menu or run `roster` from the command line. -request.headers['X-API-Key'] = apiKey; -request.headers['X-Timestamp'] = timestamp; -request.headers['X-Request-ID'] = requestId; +See the [Getting Started Guide](https://git.bugsy.cz/beval/roster/wiki/Getting-Started) for a walkthrough. -// Save for later reference -roster.setVariable('last_request_id', requestId); -console.log('Request ID:', requestId); -``` +## Documentation -### Postprocessing Scripts +Complete documentation is available in the [Wiki](https://git.bugsy.cz/beval/roster/wiki): -**Run AFTER receiving the HTTP response.** Use postprocessing to: -- Extract data from response body -- Parse JSON/XML responses -- Store values in environment variables for use in subsequent requests -- Validate response data +- **[Home](https://git.bugsy.cz/beval/roster/wiki/Home)** - Overview and quick links +- **[Installation](https://git.bugsy.cz/beval/roster/wiki/Installation)** - Build and install instructions +- **[Getting Started](https://git.bugsy.cz/beval/roster/wiki/Getting-Started)** - Your first HTTP request +- **[Projects and Environments](https://git.bugsy.cz/beval/roster/wiki/Projects-and-Environments)** - Organize your work +- **[Variables](https://git.bugsy.cz/beval/roster/wiki/Variables)** - Use variables in requests +- **[Sensitive Variables](https://git.bugsy.cz/beval/roster/wiki/Sensitive-Variables)** - Secure credential storage with GNOME Keyring +- **[Scripts](https://git.bugsy.cz/beval/roster/wiki/Scripts)** - Automate workflows with JavaScript +- **[API Reference](https://git.bugsy.cz/beval/roster/wiki/API-Reference)** - Complete JavaScript API +- **[Keyboard Shortcuts](https://git.bugsy.cz/beval/roster/wiki/Keyboard-Shortcuts)** - Speed up your workflow +- **[FAQ](https://git.bugsy.cz/beval/roster/wiki/FAQ)** - Frequently asked questions -**Available API:** -```javascript -// Response object (read-only) -response.body // Response body as string -response.headers // Object with header key-value pairs -response.statusCode // HTTP status code (e.g., 200, 404) -response.statusText // Status text (e.g., "OK", "Not Found") -response.responseTime // Response time in milliseconds +## Key Features -// Roster API -roster.setVariable(name, value) // Set/update variable -roster.setVariables({key: value}) // Batch set variables +### Secure Credential Storage -// Console output -console.log(message) // Output shown in script results -``` +Store API keys, passwords, and tokens securely in GNOME Keyring with one-click encryption. Regular variables are stored in JSON, while sensitive variables are encrypted. -**Example 1: Extract Authentication Token** -```javascript -const data = JSON.parse(response.body); -if (data.access_token) { - roster.setVariable('auth_token', data.access_token); - console.log('Saved auth token'); -} -``` +[Learn more about Sensitive Variables](https://git.bugsy.cz/beval/roster/wiki/Sensitive-Variables) -**Example 2: Extract Multiple Values** -```javascript -const data = JSON.parse(response.body); -roster.setVariables({ - user_id: data.user.id, - user_name: data.user.name, - session_id: data.session.id -}); -console.log('Extracted user:', data.user.name); -``` +### JavaScript Automation -**Example 3: Validate and Store Response** -```javascript -const data = JSON.parse(response.body); -if (response.statusCode === 200 && data.items) { - roster.setVariable('item_count', data.items.length.toString()); - if (data.items.length > 0) { - roster.setVariable('first_item_id', data.items[0].id); - } - console.log('Found', data.items.length, 'items'); -} else { - console.log('Error: Invalid response'); -} -``` +Use preprocessing and postprocessing scripts to: +- Extract authentication tokens from responses +- Add dynamic headers (timestamps, signatures) +- Chain requests together +- Validate responses -### Workflow Example: OAuth Token Flow +[Learn more about Scripts](https://git.bugsy.cz/bavel/roster/wiki/Scripts) -**Request 1 (Login) - Postprocessing:** -```javascript -// Extract and store tokens from login response -const data = JSON.parse(response.body); -roster.setVariables({ - access_token: data.access_token, - refresh_token: data.refresh_token, - user_id: data.user_id -}); -console.log('Logged in as user:', data.user_id); -``` +### Multi-Environment Support -**Request 2 (API Call) - Preprocessing:** -```javascript -// Use stored token in subsequent request -const token = roster.getVariable('access_token'); -const userId = roster.getVariable('user_id'); +Manage multiple environments (development, staging, production) with different variable values. Switch environments with one click. -request.headers['Authorization'] = 'Bearer ' + token; -request.url = request.url.replace('{userId}', userId); -console.log('Making authenticated request for user:', userId); -``` +[Learn more about Variables](https://git.bugsy.cz/beval/roster/wiki/Variables) -### Environment Variables +## Dependencies -Variables can be: -- Manually defined in "Manage Environments" -- Automatically created by scripts using `roster.setVariable()` -- Used in requests with `{{variable_name}}` syntax -- Read in preprocessing with `roster.getVariable()` +### Runtime +- GTK 4 +- libadwaita 1 +- Python 3 +- libsoup3 (provided by GNOME Platform) +- libsecret (provided by GNOME Platform) +- GJS (GNOME JavaScript) -Variables are scoped to environments within projects, allowing different values for development, staging, and production. +### Build +- Meson (>= 1.0.0) +- Ninja +- pkg-config +- gettext + +See the [Installation Guide](https://git.bugsy.cz/beval/roster/wiki/Installation) for platform-specific dependencies. + +## Platform + +Roster is built specifically for the GNOME desktop using native technologies: +- **GTK 4** - Modern UI toolkit +- **libadwaita** - GNOME design patterns +- **libsoup3** - HTTP networking +- **libsecret** - Secure credential storage +- **GJS** - JavaScript runtime for scripts + +## License + +GPL-3.0-or-later + +## Support + +- **Issues**: [git.bugsy.cz/beval/roster/issues](https://git.bugsy.cz/beval/roster/issues) +- **Wiki**: [git.bugsy.cz/beval/roster/wiki](https://git.bugsy.cz/bavel/roster/wiki) +- **Source**: [git.bugsy.cz/beval/roster](https://git.bugsy.cz/beval/roster) + +## Contributing + +Contributions are welcome! Please open an issue or pull request.