feat: add example handlers for URL transformations and update README with usage instructions

Author: manu4543

README.md

@@ -58,68 +58,31 @@ module.exports.handler = handler;
 
 ## Examples
 
-### 1. Simple URL Rewrite
+See the [`examples/`](./examples) folder for ready-to-use handler implementations:
 
-```javascript
-function handler(url, urlPrefix, context) {
-  return {
-    url: url.replace('/v1/', '/v2/')
-  };
-}
+1. **Simple URL Rewrite** - Change version in path (e.g., /v1/ to /v2/)
+2. **Path Parameters** - Extract path parameters and convert to query string
+3. **Hostname Change** - Change domain/hostname
+4. **Keyword Path Rewriting** - Rewrite paths based on keyword mapping
+5. **Query Parameter Transformation** - Transform custom query params
+6. **Access Control** - Block access to private paths and sensitive files
+7. **Error Handling** - Handle errors gracefully with fallback
+8. **Video Thumbnail** - Generate video thumbnails with image extensions
 
-module.exports.handler = handler;
-```
+Each example is a complete, working handler file that you can copy directly to `handler.js`. See [`examples/README.md`](./examples/README.md) for details.
 
-### 2. Extract Path Parameters
+### Quick Example
 
 ```javascript
 function handler(url, urlPrefix, context) {
-  // Convert: /w_100/h_200/image.jpg → /image.jpg?tr=w-100,h-200
-  const parsedUrl = new URL(url);
-  const params = [];
-  
-  parsedUrl.pathname = parsedUrl.pathname.replace(
-    /\/(w|h)_(\d+)/g,
-    (match, key, value) => {
-      params.push(`${key}-${value}`);
-      return '';
-    }
-  );
-  
-  if (params.length > 0) {
-    parsedUrl.search = `?tr=${params.join(',')}`;
-  }
-  
   return {
-    url: parsedUrl.toString(),
-    signURL: true
+    url: url.replace('/v1/', '/v2/')
   };
 }
 
 module.exports.handler = handler;
 ```
 
-### 3. Block Private Paths
-
-```javascript
-function handler(url, urlPrefix, context) {
-  const parsedUrl = new URL(url);
-  
-  if (parsedUrl.pathname.includes('/private/')) {
-    return {
-      status: 403,
-      body: { error: 'Access denied' }
-    };
-  }
-  
-  return { url };
-}
-
-module.exports.handler = handler;
-```
-
-**See [examples.js](./examples.js) for 12+ more examples** including hostname changes, routing, query transformations, and more.
-
 ## Testing
 
 ```bash

examples.js

@@ -0,0 +1,14 @@
+/**
+ * Simple URL Rewrite
+ * 
+ * Change version in path (e.g., /v1/ to /v2/)
+ */
+
+function handler(url, urlPrefix, context) {
+  // Change /v1/ to /v2/ in path
+  return {
+    url: url.replace('/v1/', '/v2/')
+  };
+}
+
+module.exports.handler = handler;

examples/01-simple-url-rewrite.js

@@ -0,0 +1,35 @@
+/**
+ * Parameter Extraction from Path
+ * 
+ * Convert path-based parameters to query string transformations
+ * Example: /w_100/h_200/image.jpg → /image.jpg?tr=w-100,h-200
+ */
+
+function handler(url, urlPrefix, context) {
+  const parsedUrl = new URL(url);
+  const params = [];
+  const regex = /\/(w|h)_(\d+)/g;
+
+  let cleanPath = parsedUrl.pathname.replace(regex, (match, key, value) => {
+    params.push(`${key}-${value}`);
+    return '';
+  });
+
+  cleanPath = cleanPath.replace(/\/{2,}/g, '/');
+
+  if (params.length > 0) {
+    parsedUrl.pathname = cleanPath;
+    parsedUrl.search = `?tr=${params.join(',')}`;
+    
+    context.logger.info({
+      transformations: params.join(',')
+    }, 'Converted path parameters to query string');
+  }
+
+  return {
+    url: parsedUrl.toString(),
+    signURL: true // Server will sign the modified URL
+  };
+}
+
+module.exports.handler = handler;

examples/02-path-parameters.js

@@ -0,0 +1,17 @@
+/**
+ * Hostname Change
+ * 
+ * Change domain from one hostname to another
+ */
+
+function handler(url, urlPrefix, context) {
+  // Change domain from old-domain.com to new-domain.com
+  const parsedUrl = new URL(url);
+  parsedUrl.hostname = 'new-domain.com';
+
+  return {
+    url: parsedUrl.toString()
+  };
+}
+
+module.exports.handler = handler;