@dytsou/shorten-url 2.4.3 → 2.4.4

package/README.md

@@ -1,231 +1,188 @@
 # URL Shortener
 
-A modern, fast URL shortener built with Cloudflare Workers and a responsive web interface. This project allows anyone to create short URLs with optional custom slugs, featuring a clean UI and robust backend with comprehensive API documentation.
+A URL shortener built with Cloudflare Workers, Cloudflare KV, and a responsive static web interface. The Worker creates short links, stores them in KV, and serves redirects; the `docs/` directory contains the website and OpenAPI reference.
+
+[![Built with Cloudflare](https://workers.cloudflare.com/built-with-cloudflare.svg)](https://cloudflare.com)
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/dytsou/shorten-url)
 
 ## Features
 
-- **URL Shortening**: Convert long URLs into short, shareable links
-- **Custom Slugs**: Create personalized short URLs (optional)
-- **Protected Shortening**: Short URL creation is protected behind Cloudflare Access / WARP for safer usage
-- **Responsive Design**: Works seamlessly on desktop and mobile devices
-- **Fast Performance**: Built on Cloudflare Workers for global edge deployment
-- **Security Features**: URL validation, rate limiting, and optional Safe Browsing integration
-- **Modern Copy Function**: One-click copying with fallbacks for all browsers
-- **Custom Error Pages**: Beautiful 404, security warning, and redirect pages (fully customizable via your GitHub Pages)
-- **API Documentation**: Interactive Swagger UI with OpenAPI 3.1.0 specification
-- **Analytics Ready**: Optional click tracking and analytics integration
+- **URL Shortening**: Create short links stored in Cloudflare KV and redirect with HTTP 302
+- **Custom Slugs**: Optionally choose a slug using letters, numbers, hyphens, or underscores
+- **Cloudflare Access**: The Worker checks for Cloudflare Access JWT and email headers before creating links
+- **Responsive Design**: Static shortening form supports desktop and mobile screens
+- **Unique Links**: Optionally reuse the same short key when the destination URL already exists
+- **URL Safety**: Validate submitted URLs and optionally check redirect destinations with Google Safe Browsing
+- **Copy Support**: Copy shortened URLs with a manual-selection fallback
+- **Hosted Error Pages**: Configure external 404, error, Safe Browsing warning, and no-referrer pages
+- **API Documentation**: Static Swagger UI with an OpenAPI 3.1 specification
+- **Worker Observability**: Structured logs and traces are supported
+
+The Worker does not implement click analytics, per-IP rate limiting, or blocked-domain lists. The similarly named settings in `config/config.js` are not used by the current Worker.
 
 ## Quick Start
 
 ### Prerequisites
 
-- A Cloudflare account with Workers enabled
-- GitHub account for hosting the frontend (or any static hosting)
-- Basic knowledge of Git and command line
+- A Cloudflare account with Workers and Pages; the Deploy to Cloudflare button provisions the required KV namespace
+- A GitHub or GitLab account to receive the repository created by the Deploy to Cloudflare button
+- A Cloudflare Pages project to publish `docs/`
+- Node.js 24 or newer and pnpm 10.22.0 for manual deployment
 
-### 1. Clone the Repository
+### 1. Deploy with Cloudflare (Recommended)
 
-```bash
-git clone https://github.com/dytsou/shorten-url.git
-cd shorten-url
-```
+1. Click the **Deploy to Cloudflare** button near the top of this README.
+2. Connect your Cloudflare and GitHub or GitLab accounts, then choose the destination repository and Worker name.
+3. Confirm the `LINKS` KV binding. Cloudflare provisions the namespace and deploys the Worker from the `main` branch.
 
-### 2. Setup Configuration
+The button deploys the Worker; it does not publish the static homepage in `docs/`. Connect the created repository to Cloudflare Pages, leave the build command blank, and set the output directory to `docs`. Then set `frontend.url` in `config/config.js` to the Pages URL and push the change to redeploy the Worker. The Worker fetches the static homepage and serves it at `/`, so the form submits to `POST /` on the Worker.
 
-```bash
-# Copy the example configuration
-cp config/config.example.js config/config.js
+### 2. Alternative: Manual Worker Deployment
+
+Clone the repository and install the pinned Wrangler version:
 
-# Edit the configuration file
-vim config/config.js
+```bash
+git clone https://github.com/dytsou/shorten-url.git
+cd shorten-url
+corepack enable
+pnpm install
 ```
 
-Update the `config/config.js` file with your settings:
+Set `frontend.url` in `config/config.js` to the public URL where you host `docs/`. The Worker fetches this page for `GET /`:
 
 ```javascript
 const config = {
   frontend: {
-    // IMPORTANT: Update this to your GitHub Pages URL or custom domain
-    url: "https://yourusername.github.io/shorten-url/",
+    url: "https://your-project.pages.dev/",
   },
-  // ... other settings
+  // Configure worker options here
 };
 ```
 
-### 3. Deploy Frontend
-
-#### Option A: GitHub Pages (Recommended)
+`src/worker.js` imports `config/config.js` directly. Keep API keys out of this file; configure the optional Google Safe Browsing key with a Wrangler secret.
 
-1. Push your code to GitHub
-2. Go to your repository settings
-3. Enable GitHub Pages for the main branch
-4. Your frontend will be available at `https://yourusername.github.io/shorten-url/`
-
-#### Option B: Custom Domain
-
-1. Upload the `docs/` directory to your web hosting
-2. Update the `frontend.url` in `config/config.js` to match your domain
-
-### 4. Setup Cloudflare Workers
-
-#### Install Wrangler CLI
+Install Wrangler, log in, and deploy:
 
 ```bash
-npm install -g wrangler
-```
-
-#### Configure Wrangler
-
-```bash
-# Login to Cloudflare
-wrangler auth login
-
-# Create a new KV namespace for storing URLs
-wrangler kv:namespace create "LINKS"
-```
-
-#### Create wrangler.toml
-
-Create a `wrangler.toml` file in your project root:
-
-```toml
-name = "url-shortener"
-main = "src/worker.js"
-compatibility_date = "2024-01-01"
-
-[[kv_namespaces]]
-binding = "LINKS"
-id = "your-kv-namespace-id-here"
+pnpm exec wrangler login
+pnpm deploy
 ```
 
-Replace `your-kv-namespace-id-here` with the ID from the KV namespace creation command.
+The `LINKS` binding in `wrangler.toml` omits an account-specific namespace ID so Wrangler can provision it. To use an existing KV namespace, create it with `pnpm exec wrangler kv namespace create LINKS` and set its ID in `wrangler.toml` before deploying.
 
-#### Deploy the Worker
+### 3. Deploy the Frontend to Cloudflare Pages
 
-```bash
-wrangler deploy
-```
+The `main` branch includes a sample page at `docs/index.html`. To create your own Pages site, connect your repository to Cloudflare Pages, set the production branch to the branch containing your homepage, leave the build command blank, and use `docs` as the output directory.
 
-### 5. Update Configuration
+This repository's Cloudflare Pages project publishes `docs/` from the `production` branch. The `main` branch remains the one-click Worker template. Set `frontend.url` to your Pages URL so the Worker can serve the hosted homepage at `/`.
 
-After deploying, update your `config/config.js` with the worker URL:
+For custom error and interstitial pages, set `frontend.pagesBase` to the directory containing those files.
 
-```javascript
-const config = {
-  frontend: {
-    url: "https://yourusername.github.io/shorten-url/",
-  },
-  // ... other settings
-};
-```
+The Worker returns short URLs using the request's origin, so configure its public domain in Cloudflare separately from `frontend.url`.
 
 ## ⚙️ Configuration Options
 
 ### Frontend Configuration
 
-| Option                   | Description                             | Default  |
-| ------------------------ | --------------------------------------- | -------- |
-| `frontend.url`           | URL where your frontend is hosted       | Required |
-| `frontend.displayDomain` | Domain shown in UI (null = auto-detect) | `null`   |
-| `frontend.theme`         | UI theme selection                      | `""`     |
+| Option                | Description                                                                 | Default  |
+| --------------------- | --------------------------------------------------------------------------- | -------- |
+| `frontend.url`        | Static homepage URL fetched by the Worker for `GET /`                      | Required |
+| `frontend.pagesBase`  | Base URL for hosted error and interstitial pages                            | `url`    |
+
+The `frontend.displayDomain` and `frontend.theme` values in the configuration are not read by the current static page or Worker.
 
 ### Worker Configuration
 
-| Option                          | Description                       | Default    |
-| ------------------------------- | --------------------------------- | ---------- |
-| `worker.no_ref`                 | Hide HTTP referrer header         | `"off"`    |
-| `worker.cors`                   | Enable CORS for API requests      | `"on"`     |
-| `worker.unique_link`            | Same URL = same short link        | `true`     |
-| `worker.custom_link`            | Allow custom slugs                | `true`     |
-| `worker.safe_browsing_api_key`  | Google Safe Browsing API key      | `""`       |
-| `worker.min_random_key_length`  | Minimum length for generated keys | `6`        |
-| `worker.max_custom_slug_length` | Maximum length for custom slugs   | `50`       |
-| `worker.reserved_slugs`         | List of reserved slugs            | See config |
+| Option                          | Description                                                     | Default    |
+| ------------------------------- | --------------------------------------------------------------- | ---------- |
+| `worker.no_ref`                 | Use the hosted no-referrer interstitial before redirecting      | `"off"`    |
+| `worker.cors`                   | Add wildcard CORS headers for API responses                     | `"on"`     |
+| `worker.unique_link`            | Reuse a key when the same URL has already been shortened        | `true`     |
+| `worker.custom_link`            | Allow custom slugs                                              | `true`     |
+| `SAFE_BROWSING_API_KEY`         | Optional Google Safe Browsing API key stored as a Worker secret  | Unset      |
+| `worker.min_random_key_length`  | Minimum length for generated keys                               | `6`        |
+| `worker.random_chars`           | Characters used for generated keys                              | See config |
+| `worker.max_custom_slug_length` | Maximum length for custom slugs                                 | `50`       |
+| `worker.reserved_slugs`         | Slugs that cannot be used as custom links                       | See config |
 
 ### Security Configuration
 
-| Option                     | Description                | Default |
-| -------------------------- | -------------------------- | ------- |
-| `security.rate_limit`      | Requests per minute per IP | `10`    |
-| `security.validate_urls`   | Enable URL validation      | `true`  |
-| `security.blocked_domains` | List of blocked domains    | `[]`    |
+| Option                                | Description                                                          | Default |
+| ------------------------------------- | -------------------------------------------------------------------- | ------- |
+| `security.rate_limit`                | Not implemented by the Worker                                        | Unused  |
+| `security.validate_urls`             | URLs are always validated; this setting does not toggle validation  | Unused  |
+| `security.blocked_domains`           | Domain blocklists are not implemented by the Worker                 | Unused  |
+| `security.block_suspicious_domains`  | Domain blocklists are not implemented by the Worker                 | Unused  |
 
 ### Storage Configuration
 
-| Option                 | Description               | Default   |
-| ---------------------- | ------------------------- | --------- |
-| `storage.binding_name` | KV namespace binding name | `"LINKS"` |
+| Option                 | Description                                                          | Default   |
+| ---------------------- | -------------------------------------------------------------------- | --------- |
+| `storage.binding_name` | Worker reads KV from `env.LINKS`; this config value is not consulted | `"LINKS"` |
 
 ## 🔧 Advanced Setup
 
 ### Custom Domain
 
-1. Add a custom domain in Cloudflare Workers dashboard
-2. Update your DNS records to point to Cloudflare
-3. Update the worker URL in your configuration
+1. Add a custom domain to the Cloudflare Pages project for the static site.
+2. Add a domain to the Cloudflare Worker separately for the shortening API.
+3. Set `frontend.url` to the Cloudflare Pages URL; Pages and Worker domains are configured independently.
 
 ### Google Safe Browsing
 
 1. Get an API key from [Google Cloud Console](https://developers.google.com/safe-browsing/v4/get-started)
-2. Add the key to your `config.js`:
+2. Store it as a Worker secret:
 
-```javascript
-worker: {
-    safe_browsing_api_key: "your-api-key-here",
-}
+```bash
+pnpm exec wrangler secret put SAFE_BROWSING_API_KEY
 ```
 
+The Worker reads this secret at runtime. The key is not stored in `config/config.js`.
+
 ### Analytics Integration
 
-Configure analytics in your `config.js`:
-
-```javascript
-analytics: {
-    enable_tracking: true,
-    ga_tracking_id: "G-XXXXXXXXXX", // Google Analytics 4
-    analytics_endpoint: "https://your-analytics-endpoint.com"
-}
-```
+Click analytics is not implemented, and the `analytics` object in `config/config.js` is not used by the Worker. Cloudflare Worker logs and traces are enabled in `wrangler.toml`.
 
 ### Custom Error Pages
 
-The system fetches error and redirect pages from your GitHub Pages repository, so you can fully customize their content and design:
-
-- **404 Page**: <code>https://dytsou.github.io/404.html</code>
-- **Security Warning**: <code>https://dytsou.github.io/safe-browsing-warning.html</code>
-- **No-Referrer Redirect**: <code>https://dytsou.github.io/no-ref-page.html</code>
+The Worker fetches optional error and interstitial pages from `frontend.pagesBase` (or `frontend.url` when `pagesBase` is not set). Add these files to your static host to customize them:
 
-You can edit these HTML files in your GitHub Pages repo to change the look, text, or behavior at any time. The worker will always serve the latest version from your site.
+- **404 Page**: `404.html`
+- **Error Page**: `error.html`
+- **Security Warning**: `safe-browsing-warning.html`
+- **No-Referrer Redirect**: `no-ref-page.html`
 
-All pages feature responsive design with glassmorphism effects matching your main interface.
+These files are not included in this repository. The Worker fetches their current contents from your static host when needed.
 
 ## 📖 API Documentation
 
-The project includes comprehensive API documentation available at `/api` endpoint with interactive Swagger UI.
+The API reference is a static Swagger UI published from `docs/api/`; it is not served by the Worker at `/api`.
 
 ### OpenAPI Specification
 
 - **Format**: OpenAPI 3.1.0
 - **Location**: [docs/api/openapi.yaml](docs/api/openapi.yaml)
-- **Interactive UI**: Available at `/api` endpoint on your deployed worker
+- **Interactive UI**: [docs/api/index.html](docs/api/index.html), published at `/api/` under the Pages base URL
 - **Offline Access**: [docs/api/index.html](docs/api/index.html) for local viewing
 
 ### Shorten URL
 
-**POST** `/shorten`
+**POST** `/`
 
 ```json
 {
   "url": "https://example.com/very-long-url",
-  "custom_slug": "my-link" // optional
+  "custom_slug": "my-link"
 }
 ```
 
-**Response:**
+`custom_slug` is optional. The default Worker template requires Cloudflare Access headers before creating a link.
+
+**Response (201 Created):**
 
 ```json
 {
-  "short_url": "https://url.tsou.me/abc123"
+  "short_url": "https://your-worker-domain.example/abc123"
 }
 ```
 
@@ -242,11 +199,12 @@ The project includes comprehensive API documentation available at `/api` endpoin
 
 **GET** `/{key}`
 
-Redirects to the original URL or shows appropriate error page.
+Redirects to the stored destination with HTTP 302. Query parameters from the short URL are appended to the destination.
 
 ### Additional Endpoints
 
-- **GET** `/api` - Interactive API documentation (Swagger UI)
+- **GET** `/` - Fetches the configured static homepage
+- **OPTIONS** - Returns a CORS preflight response
 
 ## 🛠️ Development
 
@@ -254,45 +212,46 @@ Redirects to the original URL or shows appropriate error page.
 
 ```bash
 # Start local development server (see wrangler.toml for port / host)
-wrangler dev
+pnpm dev
 
-# Test with curl (example; in production, requests must pass through Cloudflare Access/WARP)
-curl -X POST http://localhost:8787/shorten \
+# Local-only example. The handler checks for both headers; Cloudflare Access must
+# authenticate production requests before they reach the Worker.
+curl -X POST http://localhost:8787/ \
   -H "Content-Type: application/json" \
+  -H "Cf-Access-Jwt-Assertion: local-test" \
+  -H "Cf-Access-Authenticated-User-Email: you@example.com" \
   -d '{"url": "https://example.com"}'
 ```
 
+The Worker imports `config/config.js` directly. Run `pnpm test` to execute the Worker tests.
+
 ### File Structure
 
 ```
 shorten-url/
 ├── src/
-│   ├── worker.js           # Production Cloudflare Worker
-│   ├── worker.dev.js       # Development Cloudflare Worker
-│   └── worker.example.js   # Worker template
+│   ├── lib/                 # Validation, redirects, KV, responses, and observability
+│   └── worker.js            # Worker entrypoint
 ├── docs/
-│   ├── index.html          # Homepage interface
+│   ├── index.html          # Sample homepage (POST /)
 │   └── api/
 │       ├── index.html      # Swagger UI for API docs
 │       └── openapi.yaml    # OpenAPI 3.1.0 specification
 ├── config/
-│   ├── config.js           # Configuration (not in git)
-│   └── config.example.js   # Configuration template
-├── .cursor/                # Cursor IDE rules and workflow
+│   └── config.js            # Worker configuration
+├── wrangler.toml            # Wrangler configuration
 ├── .github/                # GitHub workflows and templates
-├── .gitignore             # Git ignore rules
-├── README.md              # This file
-└── wrangler.toml          # Wrangler configuration
+├── .gitignore              # Ignores local-only files
+└── README.md               # This file
 ```
 
 ## Security Considerations
 
-- Keep your `config.js` file private (it's in `.gitignore`)
-- Use environment variables for sensitive data in production
-- Enable rate limiting to prevent abuse
-- Consider enabling Google Safe Browsing for malicious URL detection
+- Keep API keys out of version control; store them with Wrangler secrets
+- Configure a Cloudflare Access policy in front of the Worker; the handler checks for Access headers but does not verify JWT signatures itself
+- The Worker has no built-in per-IP rate limit or blocked-domain list
+- Consider enabling Google Safe Browsing for redirect destinations
 - Regularly monitor your KV storage usage
-- Configure Cloudflare Access / WARP correctly, as URL shortening is intended to be available only to authenticated/requesters you control
 
 ## Troubleshooting
 
@@ -305,7 +264,8 @@ shorten-url/
 
 **Worker deployment fails:**
 
-- Check your `wrangler.toml` configuration
+- Confirm `src/worker.js` and `config/config.js` are present
+- Ensure the `LINKS` KV namespace ID in `wrangler.toml` is valid
 - Ensure KV namespace ID is correct
 - Verify you're logged into the correct Cloudflare account
 
@@ -317,13 +277,13 @@ shorten-url/
 
 **Frontend not loading:**
 
-- Update `frontend.url` in your config to match your hosting URL
-- Ensure CORS is enabled in worker configuration
+- Set `frontend.url` to the hosted static homepage URL
+- If the form returns an invalid-path response, check that its POST path matches the Worker route (`/` for the template)
+- Enable CORS if the frontend and Worker use different origins
 
 **Rate limiting issues:**
 
-- Adjust `security.rate_limit` in your configuration
-- Consider implementing IP allowlisting for trusted sources
+- The Worker does not currently rate-limit requests. Protect shortening with Cloudflare Access or add a rate limiter.
 
 ## License
 
@@ -347,12 +307,13 @@ If you encounter any issues or have questions:
 
 ## Deployment Checklist
 
-- [ ] Updated `config.js` with your settings
-- [ ] Deployed frontend to GitHub Pages or custom hosting
+- [ ] Set `frontend.url` and the `LINKS` KV namespace in the deployment configuration
+- [ ] Deployed `docs/` to Cloudflare Pages
 - [ ] Created Cloudflare KV namespace
 - [ ] Configured `wrangler.toml` with correct KV namespace ID
-- [ ] Deployed worker using `wrangler deploy`
-- [ ] Tested URL shortening functionality
+- [ ] Protected the Worker with a Cloudflare Access policy
+- [ ] Deployed the Worker using `pnpm deploy`
+- [ ] Tested URL shortening at `POST /`
 - [ ] Verified copy-to-clipboard feature works
 - [ ] Tested custom error pages (404, security warnings)
 - [ ] (Optional) Configured custom domain

package/config/{config.example.js → config.js}

@@ -1,17 +1,16 @@
 /**
- * URL Shortener Configuration Example
+ * URL Shortener deployment configuration
  *
- * Copy this file to config.js and modify the values according to your setup.
- * This file should be committed to your repository as a template.
- * The actual config.js file should be added to .gitignore to keep your secrets safe.
+ * Set frontend.url to the public static homepage that the Worker should serve.
+ * Keep private credentials out of this tracked file.
  */
 
 const config = {
   // Frontend Configuration
   frontend: {
     // URL where your frontend is hosted (used by worker to serve the main page)
-    // REQUIRED: Change this to your GitHub Pages URL or custom domain
-    url: "https://yourusername.github.io/your-repo-name/",
+    // REQUIRED: Change this to your Cloudflare Pages URL or custom domain
+    url: "https://your-project.pages.dev/",
 
     // Domain displayed in the custom slug input prefix
     // If null, will use the current domain automatically
@@ -107,12 +106,4 @@ const config = {
   },
 };
 
-// Export for use in other files
-if (typeof module !== "undefined" && module.exports) {
-  module.exports = config;
-}
-
-// Make available globally for browser usage
-if (typeof window !== "undefined") {
-  window.APP_CONFIG = config;
-}
+export default config;

package/docs/api/index.html

@@ -23,7 +23,7 @@
     <script>
       window.onload = () => {
         SwaggerUIBundle({
-          url: "openapi.yaml",
+          url: "/api/openapi.yaml",
           dom_id: "#swagger-ui",
           presets: [SwaggerUIBundle.presets.apis, SwaggerUIBundle.SwaggerUIStandalonePreset],
           layout: "BaseLayout",

package/docs/api/openapi.yaml

@@ -5,16 +5,16 @@ info:
   description: |
     A modern, fast URL shortener built with Cloudflare Workers and a responsive web interface.
     - Custom slugs are supported
-    - The homepage is served at /home
+    - The homepage is served at /
     - API is available at / (POST) for shortening URLs
     - Short URL access is via /{key} (GET)
     - Custom error pages for 404, security warnings, and redirects
 
 servers:
-  - url: https://url.tsou.me
+  - url: /
 
 paths:
-  /shorten:
+  /:
     post:
       summary: Shorten a URL
       description: Create a new shortened URL, optionally with a custom slug.
@@ -49,7 +49,7 @@ paths:
                   short_url:
                     type: string
                     format: uri
-                    example: https://url.tsou.me/abc123
+                    example: https://your-worker-domain.example/abc123
         "400":
           description: Bad request
           content:
@@ -63,6 +63,18 @@ paths:
                   message:
                     type: string
                     example: Invalid URL format
+        "403":
+          description: Cloudflare Access headers are missing
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "404":
+          description: Invalid API path
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
         "500":
           description: Server error
           content:
@@ -76,6 +88,21 @@ paths:
                   message:
                     type: string
                     example: Server error
+    get:
+      summary: Get homepage
+      description: Fetches the configured URL shortener frontend.
+      responses:
+        "200":
+          description: Homepage HTML
+          content:
+            text/html:
+              schema:
+                type: string
+    options:
+      summary: Handle CORS preflight
+      responses:
+        "204":
+          description: Preflight response
 
   /{key}:
     get:
@@ -104,19 +131,6 @@ paths:
               schema:
                 type: string
 
-  /home:
-    get:
-      summary: Get homepage
-      description: Serves the URL shortener frontend
-      responses:
-        "200":
-          description: Homepage HTML
-          content:
-            text/html:
-              schema:
-                type: string
-              example: URL shortener frontend with form interface
-
 components:
   schemas:
     ShortenRequest:

package/docs/index.html

@@ -529,7 +529,7 @@
           }
 
           // Make API call to your Cloudflare Worker
-          const response = await fetch(window.location.origin + "/shorten", {
+          const response = await fetch(window.location.origin + "/", {
             method: "POST",
             headers: {
               "Content-Type": "application/json",
@@ -660,7 +660,7 @@
           }
 
           // Make API call to shorten URL
-          const response = await fetch(window.location.origin + "/shorten", {
+          const response = await fetch(window.location.origin + "/", {
             method: "POST",
             headers: {
               "Content-Type": "application/json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dytsou/shorten-url",
-  "version": "2.4.3",
+  "version": "2.4.4",
   "description": "A modern, fast URL shortener built with Cloudflare Workers and a responsive web interface",
   "type": "module",
   "main": "src/worker.js",
@@ -27,12 +27,11 @@
   "devDependencies": {
     "prettier": "^3.7.4",
     "vite": "7.3.6",
-    "vitest": "^4.1.10",
+    "vitest": "^5.0.0",
     "wrangler": "^4.120.0"
   },
   "files": [
     "src/worker.js",
-    "src/worker.example.js",
     "src/lib/",
     "config/",
     "docs/",

package/src/{worker.example.js → worker.js}

@@ -1,7 +1,7 @@
 /**
- * URL Shortener — Cloudflare Worker (template)
+ * URL Shortener - Cloudflare Worker
  *
- * Copy this file to `src/worker.js` and wire in your config (see README).
+ * Configuration is imported from `config/config.js`.
  * Requires a KV namespace bound as `LINKS`.
  *
  * Routes:
@@ -14,33 +14,20 @@
 import { createShortener } from "./lib/shortener.js";
 import { endpointsFromFrontend } from "./lib/endpoints.js";
 import { withFetchObservability } from "./lib/observability.js";
-
-// ============================================================================
-// Configuration
-// ============================================================================
-
-let config;
-
-try {
-  if (typeof importConfig !== "undefined") {
-    config = { ...defaultConfig, ...importConfig };
-  } else {
-    throw new TypeError(
-      "Worker config is missing. Copy config/config.example.js to config/config.js and import it when building worker.js."
-    );
-  }
-} catch (error) {
-  console.error("Failed to load worker config:", error);
-  throw error;
-}
+import config from "../config/config.js";
 
 function getEndpoints() {
   return endpointsFromFrontend(config.frontend);
 }
 
-async function exampleFetchHandler(request, env) {
+async function fetchHandler(request, env) {
+  const workerConfig = {
+    ...config.worker,
+    safe_browsing_api_key:
+      env.SAFE_BROWSING_API_KEY ?? config.worker.safe_browsing_api_key,
+  };
   const shortener = createShortener({
-    worker: config.worker,
+    worker: workerConfig,
     endpoints: getEndpoints(),
     kv: env.LINKS,
   });
@@ -52,6 +39,23 @@ async function exampleFetchHandler(request, env) {
   if (request.method === "OPTIONS") {
     return new Response(null, { status: 204, headers: shortener.htmlHeaders() });
   }
+  if (
+    (request.method === "GET" || request.method === "HEAD") &&
+    (requestURL.pathname === "/api" || requestURL.pathname.startsWith("/api/"))
+  ) {
+    if (
+      requestURL.pathname !== "/api/" &&
+      /^\/api(?:\/api)*\/?$/.test(requestURL.pathname)
+    ) {
+      return Response.redirect(new URL("/api/", requestURL), 308);
+    }
+
+    const assetURL = new URL(
+      `${requestURL.pathname.slice(1)}${requestURL.search}`,
+      config.frontend.url,
+    );
+    return fetch(new Request(assetURL, { method: request.method }));
+  }
   if (request.method === "POST") {
     return shortener.handleShorten(request, requestURL, {
       apiPath: requestURL.pathname,
@@ -62,4 +66,4 @@ async function exampleFetchHandler(request, env) {
   return shortener.handleShortUrlRedirect(path, params);
 }
 
-export default withFetchObservability(exampleFetchHandler);
+export default withFetchObservability(fetchHandler);