feat: add PowerShell and wget share formats with clipboard copy and credential warnings + add URL shortening service (#89)

* Initial plan

* Add improved share functionality with PowerShell, wget, and clipboard support

Co-authored-by: MathiasVDA <[email protected]>

* Add comprehensive documentation for share functionality and URL shortener

Co-authored-by: MathiasVDA <[email protected]>

* Address code review feedback - improve auth detection and add fallback for non-standard HTTP methods

Co-authored-by: MathiasVDA <[email protected]>

* Final code quality improvements - extract constants and fix edge cases

Co-authored-by: MathiasVDA <[email protected]>

* fix wget command

* add all accept headers to the shareable code

* better layout for the warning toast

* add yourls example for the url shortener service

* Update packages/yasqe/src/sparql.ts

Co-authored-by: Copilot <[email protected]>

* Address PR review feedback - fix escaping, memory leaks, and add clipboard fallback

Co-authored-by: MathiasVDA <[email protected]>

* chore: added shortening service to dev page

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: MathiasVDA <[email protected]>
Co-authored-by: Mathias Vanden Auweele <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

dev/yasgui.html

@@ -36,6 +36,37 @@
           { endpoint: "https://data-interop.era.europa.eu/api/sparql", label: "ERA" }
         ],
         yasqe: {
+          createShortLink: async (yasqe, longUrl) => {
+            const YOURLS_API_URL = 'https://shorter.matdata.eu/api.php';
+            
+            try {
+              const params = new URLSearchParams({
+                action: 'shorturl',
+                url: longUrl,
+                format: 'json',
+              });
+              
+              const response = await fetch(`${YOURLS_API_URL}?${params.toString()}`, {
+                method: 'GET'
+              });
+              
+              if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+              }
+              
+              const data = await response.json();
+              
+              if (data.status === 'fail') {
+                throw new Error(data.message || 'Failed to shorten URL');
+              }
+              
+              return data.shorturl;
+              
+            } catch (error) {
+              console.error('YOURLS shortening error:', error);
+              throw error;
+            }
+          },
           snippets: [
             { label: "SELECT", code: "SELECT * WHERE {\n  ?s ?p ?o .\n} LIMIT 10", group: "QUERY" },
             { label: "CONSTRUCT", code: "CONSTRUCT {\n  ?s ?p ?o .\n} WHERE {\n  ?s ?p ?o .\n} LIMIT 10", group: "QUERY" },

docs/developer-guide.md

@@ -33,6 +33,7 @@ This comprehensive guide covers everything developers need to know to integrate,
     - [YASQE Configuration](#yasqe-configuration)
       - [YASQE Example](#yasqe-example)
       - [Code Snippets](#code-snippets)
+      - [Share Configuration](#share-configuration)
     - [YASR Configuration](#yasr-configuration)
       - [YASR Example](#yasr-example)
     - [Request Configuration](#request-configuration)
@@ -920,6 +921,314 @@ const yasqe = new Yasqe(document.getElementById('yasqe'), {
 });
 ```
 
+#### Share Configuration
+
+Configure how users can share their SPARQL queries with multiple output formats including URLs, cURL, PowerShell, and wget commands.
+
+**Configuration Options:**
+
+```typescript
+interface YasqeConfig {
+  // ... other config options
+  
+  // Function to create a shareable link (required to show share button)
+  createShareableLink?: (yasqe: Yasqe) => string;
+  
+  // Optional URL shortener function
+  createShortLink?: (yasqe: Yasqe, longUrl: string) => Promise<string>;
+  
+  // Function to consume/parse shared links
+  consumeShareLink?: (yasqe: Yasqe) => void;
+}
+```
+
+**Basic Share Configuration:**
+
+```javascript
+import Yasqe from '@matdata/yasqe';
+
+const yasqe = new Yasqe(document.getElementById('yasqe'), {
+  requestConfig: {
+    endpoint: 'https://dbpedia.org/sparql',
+    method: 'POST'
+  },
+  
+  // Enable share button with URL generation
+  createShareableLink: (yasqe) => {
+    const query = yasqe.getValue();
+    const endpoint = yasqe.getRequestConfig().endpoint;
+    
+    // Create shareable URL with query parameters
+    const params = new URLSearchParams({
+      query: query,
+      endpoint: endpoint
+    });
+    
+    return `${window.location.origin}${window.location.pathname}?${params.toString()}`;
+  },
+  
+  // Parse shared URLs on page load
+  consumeShareLink: (yasqe) => {
+    const params = new URLSearchParams(window.location.search);
+    const query = params.get('query');
+    const endpoint = params.get('endpoint');
+    
+    if (query) yasqe.setValue(query);
+    if (endpoint) {
+      yasqe.setRequestConfig({
+        ...yasqe.getRequestConfig(),
+        endpoint: endpoint
+      });
+    }
+  }
+});
+```
+
+**URL Shortener Configuration (Kutt Example):**
+
+Configure a URL shortener service to create shorter, more shareable links. This example shows integration with [Kutt](https://kutt.it), but any URL shortener API can be used.
+
+```javascript
+import Yasqe from '@matdata/yasqe';
+
+const yasqe = new Yasqe(document.getElementById('yasqe'), {
+  requestConfig: {
+    endpoint: 'https://dbpedia.org/sparql'
+  },
+  
+  // Basic shareable link creation
+  createShareableLink: (yasqe) => {
+    const query = yasqe.getValue();
+    const config = yasqe.getRequestConfig();
+    
+    const params = new URLSearchParams({
+      query: query,
+      endpoint: config.endpoint || ''
+    });
+    
+    return `${window.location.origin}${window.location.pathname}?${params.toString()}`;
+  },
+  
+  // URL shortener integration (Kutt example)
+  createShortLink: async (yasqe, longUrl) => {
+    const KUTT_API_URL = 'https://kutt.it/api/v2/links';
+    // Important: Load API key from a secure config or environment variable
+    // Never hardcode real API keys in source code!
+    // Example: Load from window.__CONFIG__ set by server-rendered template
+    const KUTT_API_KEY = window.__CONFIG__?.KUTT_API_KEY;
+    
+    if (!KUTT_API_KEY) {
+      throw new Error('Kutt API key not configured. Load it from a secure config or environment variable.');
+    }
+    
+    try {
+      const response = await fetch(KUTT_API_URL, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': KUTT_API_KEY
+        },
+        body: JSON.stringify({
+          target: longUrl,
+          // Optional: custom short code
+          // customurl: 'my-custom-code',
+          // Optional: domain (if using custom domain)
+          // domain: 'example.com',
+          // Optional: expiration
+          // expire_in: '2 hours'
+        })
+      });
+      
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.message || 'Failed to shorten URL');
+      }
+      
+      const data = await response.json();
+      return data.link; // Returns shortened URL
+      
+    } catch (error) {
+      console.error('URL shortening error:', error);
+      throw error; // Error will be displayed to user
+    }
+  },
+  
+  consumeShareLink: (yasqe) => {
+    const params = new URLSearchParams(window.location.search);
+    const query = params.get('query');
+    if (query) yasqe.setValue(query);
+  }
+});
+```
+
+**Other URL Shortener Examples:**
+
+*YOURLS (Your Own URL Shortener):*
+```javascript
+createShortLink: async (yasqe, longUrl) => {
+  const YOURLS_API_URL = 'https://your-domain.com/yourls-api.php'; // Your YOURLS instance
+  const YOURLS_SIGNATURE = 'your-signature-token'; // Found in YOURLS admin > Tools
+  
+  try {
+    const params = new URLSearchParams({
+      signature: YOURLS_SIGNATURE,
+      action: 'shorturl',
+      url: longUrl,
+      format: 'json',
+      // Optional: custom keyword
+      // keyword: 'my-custom-keyword'
+    });
+    
+    const response = await fetch(`${YOURLS_API_URL}?${params.toString()}`, {
+      method: 'GET'
+    });
+    
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+    
+    const data = await response.json();
+    
+    if (data.status === 'fail') {
+      throw new Error(data.message || 'Failed to shorten URL');
+    }
+    
+    return data.shorturl; // Returns shortened URL
+    
+  } catch (error) {
+    console.error('YOURLS shortening error:', error);
+    throw error;
+  }
+}
+```
+
+**Note:** YOURLS can authenticate using either a signature token (recommended) or username/password. The signature token is more secure and can be found in your YOURLS admin panel under Tools > Signature Token.
+
+*TinyURL:*
+```javascript
+createShortLink: async (yasqe, longUrl) => {
+  try {
+    const response = await fetch(
+      `https://tinyurl.com/api-create.php?url=${encodeURIComponent(longUrl)}`
+    );
+
+    if (!response.ok) {
+      throw new Error(`TinyURL request failed with status ${response.status}`);
+    }
+
+    const shortUrl = await response.text();
+
+    // Basic validation: ensure the response is a valid TinyURL link
+    let parsedUrl;
+    try {
+      parsedUrl = new URL(shortUrl);
+    } catch {
+      throw new Error('TinyURL response was not a valid URL');
+    }
+
+    if (!/^https?:\/\/(www\.)?tinyurl\.com\//.test(parsedUrl.href)) {
+      throw new Error('TinyURL response did not contain a TinyURL link');
+    }
+
+    return parsedUrl.href;
+  } catch (error) {
+    console.error('TinyURL shortening error:', error);
+    throw error;
+  }
+}
+```
+
+*Bitly:*
+```javascript
+createShortLink: async (yasqe, longUrl) => {
+  // Load token from secure config
+  const BITLY_TOKEN = window.__CONFIG__?.BITLY_TOKEN;
+  
+  if (!BITLY_TOKEN) {
+    throw new Error('Bitly token not configured');
+  }
+  
+  try {
+    const response = await fetch('https://api-ssl.bitly.com/v4/shorten', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${BITLY_TOKEN}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ long_url: longUrl })
+    });
+
+    if (!response.ok) {
+      throw new Error(`Bitly API request failed with status ${response.status}`);
+    }
+
+    const data = await response.json();
+
+    if (!data || typeof data.link !== 'string') {
+      throw new Error('Bitly API response missing expected "link" property');
+    }
+
+    return data.link;
+  } catch (error) {
+    console.error('Failed to create Bitly short link:', error);
+    throw error;
+  }
+}
+```
+
+*Custom Backend:*
+```javascript
+createShortLink: async (yasqe, longUrl) => {
+  const response = await fetch('/api/shorten', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ url: longUrl })
+  });
+  
+  const data = await response.json();
+  return data.shortUrl;
+}
+```
+
+**Share Button Features:**
+
+When the share button is enabled (by configuring `createShareableLink`), users can:
+
+1. **Copy URL** - Copies the shareable URL to clipboard
+2. **Shorten URL** - Creates and copies a shortened URL (only shown if `createShortLink` is configured)
+3. **Copy cURL** - Generates a cURL command with all headers and authentication
+4. **Copy PowerShell** - Generates a PowerShell `Invoke-WebRequest` command
+5. **Copy wget** - Generates a wget command
+
+All command formats include:
+- Complete SPARQL query
+- Endpoint URL
+- HTTP method (GET/POST)
+- All configured headers
+- Accept header (based on query type: JSON for SELECT/ASK, text/turtle for CONSTRUCT/DESCRIBE)
+- Authentication credentials (with security warning)
+- Output file specification (PowerShell only, with appropriate extension based on Accept header)
+
+**Security Considerations:**
+
+⚠️ When users copy command-line formats (cURL, PowerShell, wget) that include authentication credentials, YASQE displays a warning toast notification. This helps prevent accidental sharing of sensitive credentials.
+
+**Best Practices:**
+
+1. **Store API keys securely** - Never commit API keys to version control
+2. **Use environment variables** - Load API keys from environment or configuration
+3. **Implement rate limiting** - Prevent abuse of URL shortener services
+4. **Handle errors gracefully** - Provide user-friendly error messages
+5. **Consider privacy** - Be transparent about what data is included in shared URLs
+
+**Troubleshooting:**
+
+- If the share button doesn't appear, ensure `createShareableLink` is configured
+- If "Shorten URL" doesn't appear, check that `createShortLink` is configured
+- Check browser console for API errors when shortening fails
+- Verify API keys and endpoints are correct
+- Ensure CORS is properly configured for your URL shortener API
+
 ### YASR Configuration
 
 YASR (results viewer) specific configuration options: