@flink-app/generic-request-plugin 0.12.1-alpha.4 → 0.12.1-alpha.44

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@flink-app/generic-request-plugin",
-    "version": "0.12.1-alpha.4",
+    "version": "0.12.1-alpha.44",
     "description": "Flink plugin that makes it possible to override default request handlers and handle specific requests manually",
     "scripts": {
         "test": "echo \"Error: no test specified\"",
-        "prepublish": "tsc"
+        "prepare": "tsc"
     },
     "author": "johan@frost.se",
     "publishConfig": {
@@ -18,11 +18,11 @@
         "node-color-log": "^5.3.1"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.4",
+        "@flink-app/flink": "^0.12.1-alpha.44",
         "@types/express": "4.17.11",
         "@types/node": "22.13.10",
         "ts-node": "^9.1.1",
         "typescript": "5.4.5"
     },
-    "gitHead": "8f06a4ab98e7179322d36546756d4305fd196f5a"
+    "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113"
 }

package/readme.md

@@ -1,35 +1,372 @@
-# Flink API Docs
+# @flink-app/generic-request-plugin
 
-A FLINK plugin that makes it possible to overide the default request handler and handle a request by your own code.
+A lightweight Flink plugin that allows you to register custom request handlers with direct access to Express request and response objects. This plugin is useful when you need to bypass Flink's standard handler system and implement custom request handling logic.
 
-## Usage
+## Features
 
-Install plugin to your flink app project:
+- Register custom Express route handlers
+- Direct access to Express `req`, `res`, and Flink `app` objects
+- Support for all HTTP methods (GET, POST, PUT, DELETE)
+- Bypass Flink's standard validation and response handling
+- Useful for webhooks, custom integrations, and special endpoints
 
-```
-npm i -S @flink-app/generic-request-plugin
+## Installation
+
+```bash
+npm install @flink-app/generic-request-plugin
 ```
 
-Add and configure plugin in your app startup (probable the `index.ts` in root project):
+## Usage
 
-```
-import { genericRequestPlugin, HttpMethod} from "@flink-app/generic-request-plugin";
+### Basic Setup
+
+```typescript
+import { FlinkApp } from "@flink-app/flink";
+import { genericRequestPlugin, HttpMethod } from "@flink-app/generic-request-plugin";
 
 function start() {
   new FlinkApp<AppContext>({
     name: "My app",
     plugins: [
-        // Register plugin
-        genericRequestPlugin({
-          "path" : "/url",
-          "method" : HttpMethod.get,
-          "handler" : (req, res, app) => {
-            res.setHeader('Content-type','text/html');
-            res.end("Hello world!")
-          }
-        })
+      genericRequestPlugin({
+        path: "/custom-endpoint",
+        method: HttpMethod.get,
+        handler: (req, res, app) => {
+          res.setHeader("Content-Type", "text/html");
+          res.end("Hello world!");
+        },
+      }),
     ],
   }).start();
 }
+```
+
+## Configuration Options
+
+- `path` (required): The URL path for the endpoint (e.g., `/webhook`, `/custom`)
+- `method` (required): HTTP method for the request
+- `handler` (required): Function that handles the request
+
+## HTTP Methods
+
+The plugin supports the following HTTP methods via the `HttpMethod` enum:
+
+- `HttpMethod.get` - GET requests
+- `HttpMethod.post` - POST requests
+- `HttpMethod.put` - PUT requests
+- `HttpMethod.delete` - DELETE requests
+
+## Handler Function
+
+The handler function receives three parameters:
+
+```typescript
+handler: (req, res, app) => void
+```
+
+- `req` - Express Request object
+- `res` - Express Response object
+- `app` - FlinkApp instance (provides access to context, repos, etc.)
+
+## Examples
+
+### Simple GET Endpoint
+
+```typescript
+genericRequestPlugin({
+  path: "/hello",
+  method: HttpMethod.get,
+  handler: (req, res, app) => {
+    res.json({ message: "Hello from Flink!" });
+  },
+});
+```
+
+### POST Endpoint with JSON Body
+
+```typescript
+genericRequestPlugin({
+  path: "/webhook",
+  method: HttpMethod.post,
+  handler: (req, res, app) => {
+    const payload = req.body;
+    console.log("Received webhook:", payload);
+    res.status(200).json({ received: true });
+  },
+});
+```
+
+### Endpoint with Database Access
+
+```typescript
+genericRequestPlugin({
+  path: "/custom-data",
+  method: HttpMethod.get,
+  handler: async (req, res, app) => {
+    try {
+      const data = await app.ctx.repos.myRepo.findAll();
+      res.json({ data });
+    } catch (error) {
+      res.status(500).json({ error: "Failed to fetch data" });
+    }
+  },
+});
+```
+
+### Endpoint with Query Parameters
+
+```typescript
+genericRequestPlugin({
+  path: "/search",
+  method: HttpMethod.get,
+  handler: (req, res, app) => {
+    const query = req.query.q;
+    const results = performSearch(query);
+    res.json({ results });
+  },
+});
+```
+
+### Endpoint with Path Parameters
+
+```typescript
+genericRequestPlugin({
+  path: "/user/:id",
+  method: HttpMethod.get,
+  handler: async (req, res, app) => {
+    const userId = req.params.id;
+    const user = await app.ctx.repos.userRepo.findById(userId);
+
+    if (!user) {
+      res.status(404).json({ error: "User not found" });
+      return;
+    }
+
+    res.json({ user });
+  },
+});
+```
+
+### Custom HTML Response
+
+```typescript
+genericRequestPlugin({
+  path: "/status",
+  method: HttpMethod.get,
+  handler: (req, res, app) => {
+    const html = `
+      <!DOCTYPE html>
+      <html>
+        <head><title>Status</title></head>
+        <body>
+          <h1>System Status: OK</h1>
+          <p>All systems operational</p>
+        </body>
+      </html>
+    `;
+    res.setHeader("Content-Type", "text/html");
+    res.end(html);
+  },
+});
+```
+
+### Webhook Handler
+
+```typescript
+genericRequestPlugin({
+  path: "/webhook/stripe",
+  method: HttpMethod.post,
+  handler: async (req, res, app) => {
+    const signature = req.headers["stripe-signature"];
+    const payload = req.body;
+
+    // Verify webhook signature
+    if (!verifyStripeSignature(payload, signature)) {
+      res.status(401).json({ error: "Invalid signature" });
+      return;
+    }
+
+    // Process webhook
+    await app.ctx.repos.orderRepo.updatePaymentStatus(payload.data);
+
+    res.status(200).json({ received: true });
+  },
+});
+```
+
+### File Download Endpoint
+
+```typescript
+genericRequestPlugin({
+  path: "/download/:fileId",
+  method: HttpMethod.get,
+  handler: async (req, res, app) => {
+    const fileId = req.params.fileId;
+    const file = await app.ctx.repos.fileRepo.findById(fileId);
+
+    if (!file) {
+      res.status(404).json({ error: "File not found" });
+      return;
+    }
+
+    res.setHeader("Content-Type", file.mimeType);
+    res.setHeader("Content-Disposition", `attachment; filename="${file.name}"`);
+    res.end(file.buffer);
+  },
+});
+```
+
+### Custom Authentication
+
+```typescript
+genericRequestPlugin({
+  path: "/admin/action",
+  method: HttpMethod.post,
+  handler: async (req, res, app) => {
+    const apiKey = req.headers["x-api-key"];
+
+    // Custom authentication logic
+    if (apiKey !== process.env.ADMIN_API_KEY) {
+      res.status(401).json({ error: "Unauthorized" });
+      return;
+    }
+
+    // Perform admin action
+    const result = await performAdminAction(req.body);
+    res.json({ success: true, result });
+  },
+});
+```
+
+## Multiple Endpoints
+
+You can register multiple generic request handlers by including multiple plugin instances:
+
+```typescript
+new FlinkApp<AppContext>({
+  name: "My app",
+  plugins: [
+    genericRequestPlugin({
+      path: "/webhook/stripe",
+      method: HttpMethod.post,
+      handler: stripeWebhookHandler,
+    }),
+    genericRequestPlugin({
+      path: "/webhook/github",
+      method: HttpMethod.post,
+      handler: githubWebhookHandler,
+    }),
+    genericRequestPlugin({
+      path: "/status",
+      method: HttpMethod.get,
+      handler: statusHandler,
+    }),
+  ],
+}).start();
+```
+
+## When to Use This Plugin
+
+Use the generic request plugin when you need to:
+
+- Handle webhooks from external services
+- Implement custom authentication or authorization logic
+- Return non-JSON responses (HTML, XML, plain text, binary files)
+- Bypass Flink's request validation
+- Access low-level Express request/response objects
+- Implement server-sent events (SSE)
+- Handle file uploads/downloads with custom logic
+- Integrate with third-party services requiring specific response formats
+
+## When NOT to Use This Plugin
+
+For standard API endpoints, use Flink's built-in handler system instead:
+
+- Standard CRUD operations - Use `FlinkHttpHandler` with GET/POST/PUT/DELETE
+- Endpoints requiring validation - Use Flink's schema validation
+- Type-safe endpoints - Use Flink's typed handlers
+- Auto-documented endpoints - Use standard handlers with the API docs plugin
+
+## Access to FlinkApp Context
+
+The handler receives the full FlinkApp instance, giving you access to:
+
+```typescript
+handler: (req, res, app) => {
+  // Access repositories
+  const data = await app.ctx.repos.myRepo.findAll();
+
+  // Access plugins
+  const stripeAPI = app.ctx.plugins.stripePlugin.stripeAPI;
+
+  // Access database
+  const collection = app.db.collection("myCollection");
+
+  // Access any custom context properties
+  const config = app.ctx.config;
+}
+```
+
+## Error Handling
+
+Always implement proper error handling in your custom handlers:
 
+```typescript
+genericRequestPlugin({
+  path: "/custom",
+  method: HttpMethod.post,
+  handler: async (req, res, app) => {
+    try {
+      // Your logic here
+      const result = await performOperation(req.body);
+      res.json({ success: true, result });
+    } catch (error) {
+      console.error("Error in custom handler:", error);
+      res.status(500).json({
+        error: "Internal server error",
+        message: error.message
+      });
+    }
+  },
+});
 ```
+
+## TypeScript Support
+
+The plugin includes TypeScript definitions. For better type safety, you can type your handlers:
+
+```typescript
+import { Request, Response } from "express";
+import { FlinkApp } from "@flink-app/flink";
+
+const myHandler = async (
+  req: Request,
+  res: Response,
+  app: FlinkApp<AppContext>
+) => {
+  // Fully typed handler
+  const userId: string = req.params.id;
+  const user = await app.ctx.repos.userRepo.findById(userId);
+  res.json({ user });
+};
+
+genericRequestPlugin({
+  path: "/user/:id",
+  method: HttpMethod.get,
+  handler: myHandler,
+});
+```
+
+## Security Considerations
+
+- Always validate and sanitize input data
+- Implement authentication/authorization when needed
+- Be careful with direct database access
+- Validate webhook signatures for external integrations
+- Use HTTPS in production
+- Rate limit sensitive endpoints
+- Never expose sensitive information in error messages
+
+## License
+
+MIT