@twick/render-server 0.14.17 → 0.14.20

package/README.md

@@ -1,10 +1,12 @@
 # @twick/render-server
 
-A simple Node.js server for rendering videos using Twick.
+A Node.js package for rendering videos using Twick. Export the `renderTwickVideo` function for programmatic use, or scaffold a complete server using the CLI.
 
 ## Overview
 
-This package provides a server-side rendering solution for Twick video projects. It allows you to render video projects on the server and download the resulting video files.
+This package provides:
+- **`renderTwickVideo` function**: A programmatic API for rendering Twick videos
+- **CLI tool**: Scaffold a complete Express server to run locally on your machine
 
 ## Installation
 
@@ -14,21 +16,57 @@ npm install @twick/render-server
 pnpm add @twick/render-server
 ```
 
+**Note:** All required dependencies (`@twick/visualizer`, `@twick/media-utils`, and other Twick packages) are automatically installed with `@twick/render-server`.
+
 ## Quick Start
 
-### Starting the server
+### Option 1: Scaffold a Server (Recommended)
+
+Scaffold a complete server with all endpoints configured:
 
 ```bash
-# Development mode
-pnpm run dev
+npx @twick/render-server init
+```
 
-# Production mode
-pnpm run build
-pnpm start
+This creates a `twick-render-server` directory with:
+- Express server with POST `/api/render-video` endpoint
+- Rate limiting and security middleware
+- TypeScript configuration
+- Package.json with all dependencies
+
+Then navigate to the scaffolded directory and start the server:
+
+```bash
+cd twick-render-server
+npm install
+npm run dev  # Development mode
+# or
+npm run build && npm start  # Production mode
 ```
 
 The server will start on port 3001 by default. You can change this by setting the `PORT` environment variable.
 
+### Option 2: Use Programmatically
+
+Import and use the `renderTwickVideo` function directly:
+
+```typescript
+import { renderTwickVideo } from "@twick/render-server";
+
+const videoPath = await renderTwickVideo(
+  {
+    input: {
+      properties: { width: 1920, height: 1080 },
+      // ... your project variables
+    }
+  },
+  {
+    outFile: "my-video.mp4",
+    quality: "high"
+  }
+);
+```
+
 ## API Endpoints
 
 ### POST /api/render-video
@@ -77,17 +115,24 @@ Renders a video using Twick.
 ```json
 {
   "success": true,
-  "downloadUrl": "http://localhost:3001/download/output/my-video.mp4"
+  "downloadUrl": "http://localhost:3001/download/my-video.mp4"
 }
 ```
 
-### GET /download/:outFile
+### GET /download/:filename
+
+Downloads a rendered video file. This endpoint is rate-limited to prevent abuse.
 
-Downloads a rendered video file.
+**Rate Limits:**
+- 100 requests per 15 minutes per IP address
+- Rate limit headers are included in responses:
+  - `X-RateLimit-Limit`: Maximum requests allowed
+  - `X-RateLimit-Remaining`: Remaining requests in current window
+  - `X-RateLimit-Reset`: When the rate limit window resets
 
 ### GET /health
 
-Health check endpoint.
+Health check endpoint. Returns server status and current timestamp.
 
 ## Configuration
 
@@ -96,23 +141,50 @@ The server uses the following environment variables:
 - `PORT`: Server port (default: 3001)
 - `NODE_ENV`: Environment (development/production)
 
-## Development
+## Package Development
+
+For developing this package itself:
 
 ```bash
 # Install dependencies
 pnpm install
 
-# Start development server
-pnpm run dev
-
-# Build for production
+# Build the package
 pnpm run build
 
-# Start production server
-pnpm start
+# Clean build artifacts
+pnpm run clean
+```
+
+## API Reference
+
+### `renderTwickVideo(variables, settings)`
 
-# Test
-node test.js
+Renders a Twick video with the provided variables and settings.
+
+**Parameters:**
+- `variables` (object): Project variables containing input configuration
+- `settings` (object, optional): Render settings to override defaults
+
+**Returns:** `Promise<string>` - Path to the rendered video file
+
+**Example:**
+```typescript
+import { renderTwickVideo } from "@twick/render-server";
+
+const videoPath = await renderTwickVideo(
+  {
+    input: {
+      properties: { width: 1920, height: 1080 },
+      tracks: [/* ... */]
+    }
+  },
+  {
+    outFile: "my-video.mp4",
+    quality: "high",
+    outDir: "./output"
+  }
+);
 ```
 
 > **Note:** This server will work on Linux and macOS only. Windows is not supported.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const SERVER_TEMPLATE = `import express from "express";
+import cors from "cors";
+import path from "path";
+import { fileURLToPath } from "url";
+import { renderTwickVideo } from "@twick/render-server";
+
+const PORT = process.env.PORT || 3001;
+const BASE_PATH = \`http://localhost:\${PORT}\`;
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Rate limiting configuration
+const RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000; // 15 minutes
+const RATE_LIMIT_MAX_REQUESTS = 100; // Maximum requests per window
+const RATE_LIMIT_CLEANUP_INTERVAL_MS = 60 * 1000; // Cleanup every minute
+
+// In-memory store for rate limiting
+interface RateLimitEntry {
+  count: number;
+  resetTime: number;
+}
+
+const rateLimitStore = new Map<string, RateLimitEntry>();
+
+// Cleanup expired entries periodically
+setInterval(() => {
+  const now = Date.now();
+  for (const [key, entry] of rateLimitStore.entries()) {
+    if (now > entry.resetTime) {
+      rateLimitStore.delete(key);
+    }
+  }
+}, RATE_LIMIT_CLEANUP_INTERVAL_MS);
+
+/**
+ * Rate limiting middleware for API endpoints.
+ * Tracks request counts per IP address and enforces rate limits
+ * to prevent abuse of the render server.
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param next - Express next function
+ * 
+ * @example
+ * \`\`\`js
+ * app.use('/api', rateLimitMiddleware);
+ * // Applies rate limiting to all /api routes
+ * \`\`\`
+ */
+const rateLimitMiddleware = (req: express.Request, res: express.Response, next: express.NextFunction) => {
+  const clientIP = req.ip || req.connection.remoteAddress || 'unknown';
+  const now = Date.now();
+  
+  // Get or create rate limit entry for this IP
+  let entry = rateLimitStore.get(clientIP);
+  
+  if (!entry || now > entry.resetTime) {
+    // New window or expired entry
+    entry = {
+      count: 1,
+      resetTime: now + RATE_LIMIT_WINDOW_MS
+    };
+    rateLimitStore.set(clientIP, entry);
+  } else {
+    // Increment count in current window
+    entry.count++;
+    
+    if (entry.count > RATE_LIMIT_MAX_REQUESTS) {
+      // Rate limit exceeded
+      const retryAfter = Math.ceil((entry.resetTime - now) / 1000);
+      res.set('Retry-After', retryAfter.toString());
+      res.set('X-RateLimit-Limit', RATE_LIMIT_MAX_REQUESTS.toString());
+      res.set('X-RateLimit-Remaining', '0');
+      res.set('X-RateLimit-Reset', new Date(entry.resetTime).toISOString());
+      
+      return res.status(429).json({
+        success: false,
+        error: 'Too many requests',
+        message: \`Rate limit exceeded. Try again in \${retryAfter} seconds.\`,
+        retryAfter
+      });
+    }
+  }
+  
+  // Add rate limit headers
+  res.set('X-RateLimit-Limit', RATE_LIMIT_MAX_REQUESTS.toString());
+  res.set('X-RateLimit-Remaining', (RATE_LIMIT_MAX_REQUESTS - entry.count).toString());
+  res.set('X-RateLimit-Reset', new Date(entry.resetTime).toISOString());
+  
+  next();
+};
+
+const app = express();
+
+app.use(cors());
+app.use(express.json());
+
+// Serve static files from output directory
+app.use("/output", express.static(path.join(__dirname, "output")));
+
+/**
+ * POST endpoint for video rendering requests.
+ * Accepts project variables and settings, renders the video,
+ * and returns a download URL for the completed video.
+ *
+ * @param req - Express request object containing variables and settings
+ * @param res - Express response object
+ * 
+ * @example
+ * \`\`\`js
+ * POST /api/render-video
+ * Body: { variables: {...}, settings: {...} }
+ * Response: { success: true, downloadUrl: "..." }
+ * \`\`\`
+ */
+app.post("/api/render-video", async (req, res) => {
+  const { variables, settings } = req.body;
+
+  try {
+    const outputPath = await renderTwickVideo(variables, settings);
+    res.json({
+      success: true,
+      downloadUrl: \`\${BASE_PATH}/download/\${path.basename(outputPath)}\`,
+    });
+  } catch (error) {
+    console.error("Render error:", error);
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    });
+  }
+});
+
+/**
+ * GET endpoint for downloading rendered videos.
+ * Serves video files with rate limiting and security checks
+ * to prevent path traversal attacks.
+ *
+ * @param req - Express request object with filename parameter
+ * @param res - Express response object
+ * 
+ * @example
+ * \`\`\`js
+ * GET /download/video-123.mp4
+ * // Downloads the specified video file
+ * \`\`\`
+ */
+app.get("/download/:filename", rateLimitMiddleware, (req, res) => {
+  const outputDir = path.resolve(__dirname, "output");
+  const requestedPath = path.resolve(outputDir, req.params.filename);
+  if (!requestedPath.startsWith(outputDir + path.sep)) {
+    // Attempted path traversal or access outside output directory
+    res.status(403).json({
+      success: false,
+      error: "Forbidden",
+    });
+    return;
+  }
+  res.download(requestedPath, (err) => {
+    if (err) {
+      res.status(404).json({
+        success: false,
+        error: "File not found",
+      });
+    }
+  });
+});
+
+/**
+ * Health check endpoint for monitoring server status.
+ * Returns server status and current timestamp for health monitoring.
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * 
+ * @example
+ * \`\`\`js
+ * GET /health
+ * Response: { status: "ok", timestamp: "2024-01-01T00:00:00.000Z" }
+ * \`\`\`
+ */
+app.get("/health", (req, res) => {
+  res.json({
+    status: "ok",
+    timestamp: new Date().toISOString(),
+  });
+});
+
+// Start the server
+app.listen(PORT, () => {
+  console.log(\`Render server running on port \${PORT}\`);
+  console.log(\`Health check: \${BASE_PATH}/health\`);
+  console.log(\`API endpoint: \${BASE_PATH}/api/render-video\`);
+  console.log(\`Download endpoint rate limited: \${RATE_LIMIT_MAX_REQUESTS} requests per \${RATE_LIMIT_WINDOW_MS / 60000} minutes\`);
+});
+`;
+const PACKAGE_JSON_TEMPLATE = `{
+  "name": "twick-render-server",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js"
+  },
+  "dependencies": {
+    "@twick/render-server": "^0.14.11",
+    "cors": "^2.8.5",
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "5.4.2"
+  }
+}
+`;
+const TSCONFIG_TEMPLATE = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "noEmit": false
+  },
+  "include": ["server.ts"],
+  "exclude": ["node_modules", "dist"]
+}
+`;
+const GITIGNORE_TEMPLATE = `node_modules/
+dist/
+output/
+.env
+*.log
+`;
+function scaffoldServer() {
+    const currentDir = process.cwd();
+    const serverDir = path.join(currentDir, "twick-render-server");
+    // Check if directory already exists
+    if (fs.existsSync(serverDir)) {
+        console.error(`Error: Directory "${serverDir}" already exists.`);
+        console.error("Please remove it or choose a different location.");
+        process.exit(1);
+    }
+    // Create server directory
+    fs.mkdirSync(serverDir, { recursive: true });
+    fs.mkdirSync(path.join(serverDir, "output"), { recursive: true });
+    // Write server.ts
+    fs.writeFileSync(path.join(serverDir, "server.ts"), SERVER_TEMPLATE, "utf-8");
+    // Write package.json
+    fs.writeFileSync(path.join(serverDir, "package.json"), PACKAGE_JSON_TEMPLATE, "utf-8");
+    // Write tsconfig.json
+    fs.writeFileSync(path.join(serverDir, "tsconfig.json"), TSCONFIG_TEMPLATE, "utf-8");
+    // Write .gitignore
+    fs.writeFileSync(path.join(serverDir, ".gitignore"), GITIGNORE_TEMPLATE, "utf-8");
+    console.log(`✅ Successfully scaffolded Twick render server!`);
+    console.log(`\n📁 Server created at: ${serverDir}`);
+    console.log(`\n📝 Next steps:`);
+    console.log(`   1. cd ${path.basename(serverDir)}`);
+    console.log(`   2. npm install`);
+    console.log(`   3. npm run dev (for development)`);
+    console.log(`   4. npm run build && npm start (for production)`);
+}
+// Parse command line arguments
+const args = process.argv.slice(2);
+const command = args[0];
+if (command === "init") {
+    scaffoldServer();
+}
+else {
+    console.log("Usage: npx twick-render-server init");
+    console.log("\nThis command scaffolds a new Twick render server in the current directory.");
+    process.exit(1);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,3 +1,2 @@
 export { default as renderTwickVideo } from "./renderer";
-export { default as createServer } from "./server";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGzD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,5 +1,3 @@
 // Export the renderer function
 export { default as renderTwickVideo } from "./renderer";
-// Re-export the server for programmatic usage
-export { default as createServer } from "./server";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEzD,8CAA8C;AAC9C,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@twick/render-server",
-  "version": "0.14.17",
+  "version": "0.14.20",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
-  "main": "dist/server.js",
+  "main": "dist/index.js",
+  "bin": {
+    "twick-render-server": "./dist/cli.js"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsx watch src/server.ts",
@@ -14,13 +17,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@twick/2d": "0.14.17",
-    "@twick/core": "0.14.17",
-    "@twick/ffmpeg": "0.14.17",
-    "@twick/renderer": "0.14.17",
-    "@twick/ui": "0.14.17",
-    "@twick/visualizer": "0.14.17",
-    "@types/express-rate-limit": "^6.0.2",
+    "@twick/2d": "^0.14.20",
+    "@twick/core": "^0.14.20",
+    "@twick/ffmpeg": "^0.14.20",
+    "@twick/renderer": "^0.14.20",
+    "@twick/ui": "^0.14.20",
+    "@twick/visualizer": "0.14.20",
     "cors": "^2.8.5",
     "express": "^4.18.2",
     "express-rate-limit": "^8.0.1",

package/package.json.bak

@@ -1,9 +1,12 @@
 {
   "name": "@twick/render-server",
-  "version": "0.14.17",
+  "version": "0.14.20",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
-  "main": "dist/server.js",
+  "main": "dist/index.js",
+  "bin": {
+    "twick-render-server": "./dist/cli.js"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsx watch src/server.ts",
@@ -14,13 +17,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@twick/2d": "0.14.17",
-    "@twick/core": "0.14.17",
-    "@twick/ffmpeg": "0.14.17",
-    "@twick/renderer": "0.14.17",
-    "@twick/ui": "0.14.17",
-    "@twick/visualizer": "0.14.17",
-    "@types/express-rate-limit": "^6.0.2",
+    "@twick/2d": "^0.14.20",
+    "@twick/core": "^0.14.20",
+    "@twick/ffmpeg": "^0.14.20",
+    "@twick/renderer": "^0.14.20",
+    "@twick/ui": "^0.14.20",
+    "@twick/visualizer": "0.14.20",
     "cors": "^2.8.5",
     "express": "^4.18.2",
     "express-rate-limit": "^8.0.1",

package/src/cli.ts

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const SERVER_TEMPLATE = `import express from "express";
+import cors from "cors";
+import path from "path";
+import { fileURLToPath } from "url";
+import { renderTwickVideo } from "@twick/render-server";
+
+const PORT = process.env.PORT || 3001;
+const BASE_PATH = \`http://localhost:\${PORT}\`;
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Rate limiting configuration
+const RATE_LIMIT_WINDOW_MS = 15 * 60 * 1000; // 15 minutes
+const RATE_LIMIT_MAX_REQUESTS = 100; // Maximum requests per window
+const RATE_LIMIT_CLEANUP_INTERVAL_MS = 60 * 1000; // Cleanup every minute
+
+// In-memory store for rate limiting
+interface RateLimitEntry {
+  count: number;
+  resetTime: number;
+}
+
+const rateLimitStore = new Map<string, RateLimitEntry>();
+
+// Cleanup expired entries periodically
+setInterval(() => {
+  const now = Date.now();
+  for (const [key, entry] of rateLimitStore.entries()) {
+    if (now > entry.resetTime) {
+      rateLimitStore.delete(key);
+    }
+  }
+}, RATE_LIMIT_CLEANUP_INTERVAL_MS);
+
+/**
+ * Rate limiting middleware for API endpoints.
+ * Tracks request counts per IP address and enforces rate limits
+ * to prevent abuse of the render server.
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param next - Express next function
+ * 
+ * @example
+ * \`\`\`js
+ * app.use('/api', rateLimitMiddleware);
+ * // Applies rate limiting to all /api routes
+ * \`\`\`
+ */
+const rateLimitMiddleware = (req: express.Request, res: express.Response, next: express.NextFunction) => {
+  const clientIP = req.ip || req.connection.remoteAddress || 'unknown';
+  const now = Date.now();
+  
+  // Get or create rate limit entry for this IP
+  let entry = rateLimitStore.get(clientIP);
+  
+  if (!entry || now > entry.resetTime) {
+    // New window or expired entry
+    entry = {
+      count: 1,
+      resetTime: now + RATE_LIMIT_WINDOW_MS
+    };
+    rateLimitStore.set(clientIP, entry);
+  } else {
+    // Increment count in current window
+    entry.count++;
+    
+    if (entry.count > RATE_LIMIT_MAX_REQUESTS) {
+      // Rate limit exceeded
+      const retryAfter = Math.ceil((entry.resetTime - now) / 1000);
+      res.set('Retry-After', retryAfter.toString());
+      res.set('X-RateLimit-Limit', RATE_LIMIT_MAX_REQUESTS.toString());
+      res.set('X-RateLimit-Remaining', '0');
+      res.set('X-RateLimit-Reset', new Date(entry.resetTime).toISOString());
+      
+      return res.status(429).json({
+        success: false,
+        error: 'Too many requests',
+        message: \`Rate limit exceeded. Try again in \${retryAfter} seconds.\`,
+        retryAfter
+      });
+    }
+  }
+  
+  // Add rate limit headers
+  res.set('X-RateLimit-Limit', RATE_LIMIT_MAX_REQUESTS.toString());
+  res.set('X-RateLimit-Remaining', (RATE_LIMIT_MAX_REQUESTS - entry.count).toString());
+  res.set('X-RateLimit-Reset', new Date(entry.resetTime).toISOString());
+  
+  next();
+};
+
+const app = express();
+
+app.use(cors());
+app.use(express.json());
+
+// Serve static files from output directory
+app.use("/output", express.static(path.join(__dirname, "output")));
+
+/**
+ * POST endpoint for video rendering requests.
+ * Accepts project variables and settings, renders the video,
+ * and returns a download URL for the completed video.
+ *
+ * @param req - Express request object containing variables and settings
+ * @param res - Express response object
+ * 
+ * @example
+ * \`\`\`js
+ * POST /api/render-video
+ * Body: { variables: {...}, settings: {...} }
+ * Response: { success: true, downloadUrl: "..." }
+ * \`\`\`
+ */
+app.post("/api/render-video", async (req, res) => {
+  const { variables, settings } = req.body;
+
+  try {
+    const outputPath = await renderTwickVideo(variables, settings);
+    res.json({
+      success: true,
+      downloadUrl: \`\${BASE_PATH}/download/\${path.basename(outputPath)}\`,
+    });
+  } catch (error) {
+    console.error("Render error:", error);
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : "Unknown error",
+    });
+  }
+});
+
+/**
+ * GET endpoint for downloading rendered videos.
+ * Serves video files with rate limiting and security checks
+ * to prevent path traversal attacks.
+ *
+ * @param req - Express request object with filename parameter
+ * @param res - Express response object
+ * 
+ * @example
+ * \`\`\`js
+ * GET /download/video-123.mp4
+ * // Downloads the specified video file
+ * \`\`\`
+ */
+app.get("/download/:filename", rateLimitMiddleware, (req, res) => {
+  const outputDir = path.resolve(__dirname, "output");
+  const requestedPath = path.resolve(outputDir, req.params.filename);
+  if (!requestedPath.startsWith(outputDir + path.sep)) {
+    // Attempted path traversal or access outside output directory
+    res.status(403).json({
+      success: false,
+      error: "Forbidden",
+    });
+    return;
+  }
+  res.download(requestedPath, (err) => {
+    if (err) {
+      res.status(404).json({
+        success: false,
+        error: "File not found",
+      });
+    }
+  });
+});
+
+/**
+ * Health check endpoint for monitoring server status.
+ * Returns server status and current timestamp for health monitoring.
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * 
+ * @example
+ * \`\`\`js
+ * GET /health
+ * Response: { status: "ok", timestamp: "2024-01-01T00:00:00.000Z" }
+ * \`\`\`
+ */
+app.get("/health", (req, res) => {
+  res.json({
+    status: "ok",
+    timestamp: new Date().toISOString(),
+  });
+});
+
+// Start the server
+app.listen(PORT, () => {
+  console.log(\`Render server running on port \${PORT}\`);
+  console.log(\`Health check: \${BASE_PATH}/health\`);
+  console.log(\`API endpoint: \${BASE_PATH}/api/render-video\`);
+  console.log(\`Download endpoint rate limited: \${RATE_LIMIT_MAX_REQUESTS} requests per \${RATE_LIMIT_WINDOW_MS / 60000} minutes\`);
+});
+`;
+
+const PACKAGE_JSON_TEMPLATE = `{
+  "name": "twick-render-server",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js"
+  },
+  "dependencies": {
+    "@twick/render-server": "^0.14.11",
+    "cors": "^2.8.5",
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.17",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "5.4.2"
+  }
+}
+`;
+
+const TSCONFIG_TEMPLATE = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "noEmit": false
+  },
+  "include": ["server.ts"],
+  "exclude": ["node_modules", "dist"]
+}
+`;
+
+const GITIGNORE_TEMPLATE = `node_modules/
+dist/
+output/
+.env
+*.log
+`;
+
+function scaffoldServer() {
+  const currentDir = process.cwd();
+  const serverDir = path.join(currentDir, "twick-render-server");
+
+  // Check if directory already exists
+  if (fs.existsSync(serverDir)) {
+    console.error(`Error: Directory "${serverDir}" already exists.`);
+    console.error("Please remove it or choose a different location.");
+    process.exit(1);
+  }
+
+  // Create server directory
+  fs.mkdirSync(serverDir, { recursive: true });
+  fs.mkdirSync(path.join(serverDir, "output"), { recursive: true });
+
+  // Write server.ts
+  fs.writeFileSync(
+    path.join(serverDir, "server.ts"),
+    SERVER_TEMPLATE,
+    "utf-8"
+  );
+
+  // Write package.json
+  fs.writeFileSync(
+    path.join(serverDir, "package.json"),
+    PACKAGE_JSON_TEMPLATE,
+    "utf-8"
+  );
+
+  // Write tsconfig.json
+  fs.writeFileSync(
+    path.join(serverDir, "tsconfig.json"),
+    TSCONFIG_TEMPLATE,
+    "utf-8"
+  );
+
+  // Write .gitignore
+  fs.writeFileSync(
+    path.join(serverDir, ".gitignore"),
+    GITIGNORE_TEMPLATE,
+    "utf-8"
+  );
+
+  console.log(`✅ Successfully scaffolded Twick render server!`);
+  console.log(`\n📁 Server created at: ${serverDir}`);
+  console.log(`\n📝 Next steps:`);
+  console.log(`   1. cd ${path.basename(serverDir)}`);
+  console.log(`   2. npm install`);
+  console.log(`   3. npm run dev (for development)`);
+  console.log(`   4. npm run build && npm start (for production)`);
+}
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === "init") {
+  scaffoldServer();
+} else {
+  console.log("Usage: npx twick-render-server init");
+  console.log("\nThis command scaffolds a new Twick render server in the current directory.");
+  process.exit(1);
+}
+

package/src/index.ts

@@ -1,5 +1,3 @@
 // Export the renderer function
 export { default as renderTwickVideo } from "./renderer";
 
-// Re-export the server for programmatic usage
-export { default as createServer } from "./server";