throttl-express 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Throttl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# @throttl/express
+
+Express middleware for [Throttl](https://throttl.xyz) API rate limiting.
+
+## Installation
+
+```bash
+npm install @throttl/express
+```
+
+## Quick Start
+
+```javascript
+import express from 'express';
+import { throttl } from '@throttl/express';
+
+const app = express();
+
+// Add Throttl middleware
+app.use(throttl({
+  serverUrl: 'https://api.throttl.xyz'
+}));
+
+// Your routes are now protected
+app.get('/api/data', (req, res) => {
+  // Access rate limit info via req.throttl
+  console.log(`Remaining requests: ${req.throttl?.remaining}`);
+  res.json({ data: 'protected!' });
+});
+
+app.listen(3000);
+```
+
+## Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `serverUrl` | `string` | Yes | Throttl API server URL |
+| `extractKey` | `function` | No | Custom function to extract API key from request |
+| `onError` | `function` | No | Custom error handler |
+
+### Default Key Extraction
+
+By default, the middleware looks for the API key in:
+1. `x-api-key` header
+2. `Authorization: Bearer <key>` header
+3. `api_key` query parameter
+
+### Custom Key Extraction
+
+```javascript
+app.use(throttl({
+  serverUrl: 'https://api.throttl.xyz',
+  extractKey: (req) => req.headers['x-custom-key']
+}));
+```
+
+### Custom Error Handling
+
+```javascript
+app.use(throttl({
+  serverUrl: 'https://api.throttl.xyz',
+  onError: (error, req, res) => {
+    console.error('Rate limit error:', error);
+    res.status(500).json({ error: 'Service unavailable' });
+  }
+}));
+```
+
+## Response
+
+The middleware adds a `throttl` object to the request:
+
+```typescript
+interface ThrottlInfo {
+  valid: boolean;
+  remaining?: number;
+  error?: string;
+}
+
+// Access in your route handlers
+app.get('/api/data', (req, res) => {
+  if (req.throttl?.remaining < 100) {
+    res.set('X-RateLimit-Warning', 'Approaching limit');
+  }
+  res.json({ data: '...' });
+});
+```
+
+## Error Responses
+
+| Status | Error | Description |
+|--------|-------|-------------|
+| 401 | `API key required` | No API key provided |
+| 401 | `invalid_key` | API key not found or inactive |
+| 429 | `quota_exceeded` | Monthly quota exhausted |
+| 503 | `Rate limit service unavailable` | Throttl API unreachable |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { throttl, type ThrottlOptions, type ThrottlInfo } from './middleware';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.throttl = void 0;
+var middleware_1 = require("./middleware");
+Object.defineProperty(exports, "throttl", { enumerable: true, get: function () { return middleware_1.throttl; } });

package/dist/middleware.d.ts

@@ -0,0 +1,19 @@
+import type { Request, Response, NextFunction } from 'express';
+export interface ThrottlOptions {
+    serverUrl: string;
+    extractKey?: (req: Request) => string | undefined;
+    onError?: (error: Error, req: Request, res: Response) => void;
+}
+export interface ThrottlInfo {
+    valid: boolean;
+    remaining?: number;
+    error?: string;
+}
+declare global {
+    namespace Express {
+        interface Request {
+            throttl?: ThrottlInfo;
+        }
+    }
+}
+export declare function throttl(options: ThrottlOptions): (req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>;

package/dist/middleware.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.throttl = throttl;
+const defaultExtractKey = (req) => {
+    return (req.headers['x-api-key'] ||
+        (req.headers['authorization']?.replace('Bearer ', '')) ||
+        req.query.api_key);
+};
+function throttl(options) {
+    const { serverUrl, extractKey = defaultExtractKey, onError } = options;
+    const validateUrl = `${serverUrl.replace(/\/$/, '')}/api/validate`;
+    return async (req, res, next) => {
+        const key = extractKey(req);
+        if (!key) {
+            return res.status(401).json({
+                error: 'API key required',
+                message: 'Provide key via x-api-key header, Authorization Bearer, or api_key query param',
+            });
+        }
+        try {
+            const response = await fetch(validateUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ key }),
+            });
+            const result = await response.json();
+            req.throttl = result;
+            if (!result.valid) {
+                const status = result.error === 'quota_exceeded' ? 429 : 401;
+                return res.status(status).json({
+                    error: result.error,
+                    remaining: result.remaining,
+                });
+            }
+            next();
+        }
+        catch (error) {
+            if (onError) {
+                onError(error, req, res);
+            }
+            else {
+                console.error('Throttl validation error:', error);
+                res.status(503).json({ error: 'Rate limit service unavailable' });
+            }
+        }
+    };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "throttl-express",
+  "version": "1.0.0",
+  "description": "Express middleware for Throttl API rate limiting",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "throttl",
+    "rate-limit",
+    "api-key",
+    "express",
+    "middleware",
+    "quota",
+    "usage-tracking"
+  ],
+  "author": "Throttl",
+  "license": "MIT",
+  "homepage": "https://throttl.xyz",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wahans/throttl.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/wahans/throttl/issues"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.2"
+  }
+}