add readme

README.md

@@ -0,0 +1,76 @@
+# URL Cleaner
+
+A Cloudflare Worker that removes tracking parameters from URLs using the official ClearURLs rule database. Provides the same privacy protection as the ClearURLs browser extension but as a serverless API.
+
+## Usage
+
+### Clean URLs
+
+**API Endpoint**: `GET /?url=<encoded-url>`
+
+```bash
+# Remove UTM tracking
+curl "https://your-worker.workers.dev/?url=https%3A//example.com%3Futm_source%3Dtest"
+# Returns: https://example.com
+
+# Clean YouTube URL (preserves video ID, removes tracking)
+curl "https://your-worker.workers.dev/?url=https%3A//youtube.com/watch%3Fv%3Dabc%26feature%3Dshare"
+# Returns: https://youtube.com/watch?v=abc
+
+# Clean URL with fragments/hash parameters
+curl "https://your-worker.workers.dev/?url=https%3A//example.com/page%3Futm_source%3Dtest%23utm_campaign%3Dfragment"
+# Returns: https://example.com/page
+```
+
+### Purge Cache
+
+**API Endpoint**: `DELETE /?url=<encoded-url>`
+
+```bash
+# Delete cached response for a specific URL
+curl -X DELETE "https://your-worker.workers.dev/?url=https%3A//example.com%3Futm_source%3Dtest"
+# Returns: Cache entry deleted (200) or Cache entry not found (404)
+```
+
+## Features
+
+- **Official ClearURLs Rules** - Uses the same 250+ provider rule database as the ClearURLs browser extension
+- **Live Rule Updates** - Automatically fetches and validates rules from ClearURLs API with SHA256 verification
+- **Query & Fragment Cleaning** - Removes tracking from both URL parameters (`?utm_source=test`) and fragments (`#utm_campaign=test`)
+- **Redirect Following** - Unwraps shortened URLs and tracking redirects (up to 5 levels)
+- **Provider-Specific Logic** - Domain-specific rules prevent false positives (e.g., TikTok rules won't affect YouTube)
+- **Advanced Pattern Matching** - Full regex support with exact ClearURLs compatibility
+- **Response Caching** - 1-hour cache using Cloudflare Cache API for improved performance and reduced latency
+- **Cache Management** - DELETE endpoint for manual cache purging and testing
+- **Durable Object Storage** - 7-day rule caching with automatic refresh and fallback support
+
+## Deployment
+
+```bash
+npm install
+npm run deploy
+```
+
+## Development
+
+```bash
+npm run dev     # Start local server at http://localhost:8787
+npm test        # Run tests
+npm run format  # Format code with Prettier
+```
+
+## Architecture
+
+- **Cloudflare Workers** - Serverless edge computing for global performance
+- **Durable Objects** - Persistent storage for ClearURLs rule caching with SHA256 validation
+- **TypeScript** - Full type safety with generated Cloudflare Workers types
+- **ClearURLs Integration** - Official rule database with automatic updates
+
+## Rule System
+
+The worker fetches and caches rules from the official ClearURLs API:
+
+- **Source**: `https://rules2.clearurls.xyz/data.minify.json`
+- **Validation**: `https://rules2.clearurls.xyz/rules.minify.hash`
+- **Cache Duration**: 7 days with automatic refresh
+- **Fallback**: Uses cached rules if fresh fetch fails