unlimit-keys 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# unlimit-keys
+
+A generic, distributed API key rotator that uses Redis to select the least recently used (LRU) key from a pool. Ideal for distributing load across multiple API keys to avoid rate limits, regardless of the provider (Google, OpenAI, Anthropic, etc.).
+
+## Installation
+
+```bash
+npm install unlimit-keys
+```
+
+## Setup
+
+### 1. Environment Variables
+
+Create a `.env.local` file with your Redis credentials and API keys:
+
+```env
+# Upstash Redis credentials
+REDIS_URL=https://your-redis-url.upstash.io
+REDIS_TOKEN=your-token
+
+# Comma-separated or newline-separated API keys
+RU_API_KEYS="key1,key2,key3"
+```
+
+### 2. Sync Keys to Redis
+
+Run the sync script to load your API keys into the global Redis pool:
+
+```bash
+npx unlimit-keys sync
+```
+
+## Usage
+
+### Programmatic API
+
+```typescript
+import { getLeastUsedKey } from 'unlimit-keys';
+
+// Get the least recently used key
+const apiKey = await getLeastUsedKey();
+console.log(apiKey);
+```
+
+### CLI
+
+```bash
+# Get the least recently used key via CLI
+npx unlimit-keys get-key
+```
+
+## How It Works
+
+1.  **Key Pool**: Keys are stored in a single Redis Sorted Set (`ru_api_keys`).
+2.  **LRU Rotation**: When you request a key, the library atomically:
+    *   Finds the key with the lowest score (oldest usage timestamp).
+    *   Updates that key's score to the current timestamp.
+    *   Returns the key.
+3.  **Concurrency**: Atomic Lua scripts ensure no race conditions, even with high concurrency across serverless functions.
+
+## License
+
+ISC

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,41 @@
+#!/usr/bin/env node
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const getLeastUsedKey_1 = require("./schema/getLeastUsedKey");
+const program = new commander_1.Command();
+program
+    .name('unlimit-keys')
+    .description('Distributed LRU API key rotation using Redis')
+    .version('0.1.0');
+program
+    .command('get-key')
+    .description('Get the least recently used API key')
+    .action(() => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        const key = yield (0, getLeastUsedKey_1.getLeastUsedKey)();
+        console.log(key);
+    }
+    catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}));
+program
+    .command('sync')
+    .description('Sync API keys from RU_API_KEYS env var to Redis')
+    .action(() => {
+    console.log('Please run: npx unlimit-keys sync');
+    console.log('Or: node dist/scripts/sync-api-keys.js');
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;;;;;;;;AACA,yCAAoC;AACpC,8DAA2D;AAE3D,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,cAAc,CAAC;KACpB,WAAW,CAAC,8CAA8C,CAAC;KAC3D,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,OAAO;KACJ,OAAO,CAAC,SAAS,CAAC;KAClB,WAAW,CAAC,qCAAqC,CAAC;KAClD,MAAM,CAAC,GAAS,EAAE;IACjB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,IAAA,iCAAe,GAAE,CAAC;QACpC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACnB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACxE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAA,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,iDAAiD,CAAC;KAC9D,MAAM,CAAC,GAAG,EAAE;IACX,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;IACjD,OAAO,CAAC,GAAG,CAAC,wCAAwC,CAAC,CAAC;AACxD,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { getLeastUsedKey } from './schema/getLeastUsedKey';
+export { redis } from './schema/redis';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redis = exports.getLeastUsedKey = void 0;
+var getLeastUsedKey_1 = require("./schema/getLeastUsedKey");
+Object.defineProperty(exports, "getLeastUsedKey", { enumerable: true, get: function () { return getLeastUsedKey_1.getLeastUsedKey; } });
+var redis_1 = require("./schema/redis");
+Object.defineProperty(exports, "redis", { enumerable: true, get: function () { return redis_1.redis; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,4DAA2D;AAAlD,kHAAA,eAAe,OAAA;AACxB,wCAAuC;AAA9B,8FAAA,KAAK,OAAA"}

package/dist/schema/getLeastUsedKey.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Fetches the least recently used API key from the global pool.
+ * Automatically updates the key's usage timestamp.
+ *
+ * @returns The API key to be used.
+ * @throws Will throw an error if no keys are found.
+ */
+export declare function getLeastUsedKey(): Promise<string>;
+//# sourceMappingURL=getLeastUsedKey.d.ts.map

package/dist/schema/getLeastUsedKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getLeastUsedKey.d.ts","sourceRoot":"","sources":["../../src/schema/getLeastUsedKey.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAwBvD"}

package/dist/schema/getLeastUsedKey.js

@@ -0,0 +1,45 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLeastUsedKey = getLeastUsedKey;
+const redis_1 = require("./redis");
+const KEY_SET = 'ru_api_keys';
+/**
+ * Fetches the least recently used API key from the global pool.
+ * Automatically updates the key's usage timestamp.
+ *
+ * @returns The API key to be used.
+ * @throws Will throw an error if no keys are found.
+ */
+function getLeastUsedKey() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const currentTime = Date.now() / 1000;
+        // Atomic Lua script:
+        // 1. Get the key with the lowest score (least recently used)
+        // 2. If a key exists, update its score to current time
+        // 3. Return the key
+        const script = `
+        local key = redis.call('zrange', KEYS[1], 0, 0)[1]
+        if key then
+            redis.call('zadd', KEYS[1], ARGV[1], key)
+            return key
+        else
+            return nil
+        end
+    `;
+        const key = yield redis_1.redis.eval(script, [KEY_SET], [currentTime]);
+        if (!key) {
+            throw new Error('No API keys found in Redis. Please check your RU_API_KEYS environment variable and run the sync script.');
+        }
+        return key;
+    });
+}
+//# sourceMappingURL=getLeastUsedKey.js.map

package/dist/schema/getLeastUsedKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getLeastUsedKey.js","sourceRoot":"","sources":["../../src/schema/getLeastUsedKey.ts"],"names":[],"mappings":";;;;;;;;;;;AAWA,0CAwBC;AAnCD,mCAAgC;AAEhC,MAAM,OAAO,GAAG,aAAa,CAAC;AAE9B;;;;;;GAMG;AACH,SAAsB,eAAe;;QACjC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QAEtC,qBAAqB;QACrB,6DAA6D;QAC7D,uDAAuD;QACvD,oBAAoB;QACpB,MAAM,MAAM,GAAG;;;;;;;;KAQd,CAAC;QAEF,MAAM,GAAG,GAAG,MAAM,aAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,WAAW,CAAC,CAAkB,CAAC;QAEhF,IAAI,CAAC,GAAG,EAAE,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,yGAAyG,CAAC,CAAC;QAC/H,CAAC;QAED,OAAO,GAAG,CAAC;IACf,CAAC;CAAA"}

package/dist/schema/redis.d.ts

@@ -0,0 +1,3 @@
+import { Redis } from '@upstash/redis';
+export declare const redis: Redis;
+//# sourceMappingURL=redis.d.ts.map

package/dist/schema/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/schema/redis.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAMvC,eAAO,MAAM,KAAK,OAGhB,CAAC"}

package/dist/schema/redis.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redis = void 0;
+const redis_1 = require("@upstash/redis");
+if (!process.env.REDIS_URL || !process.env.REDIS_TOKEN) {
+    throw new Error('Missing Redis credentials. Please set REDIS_URL and REDIS_TOKEN.');
+}
+exports.redis = new redis_1.Redis({
+    url: process.env.REDIS_URL,
+    token: process.env.REDIS_TOKEN,
+});
+//# sourceMappingURL=redis.js.map

package/dist/schema/redis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.js","sourceRoot":"","sources":["../../src/schema/redis.ts"],"names":[],"mappings":";;;AAAA,0CAAuC;AAEvC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;IACvD,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;AACtF,CAAC;AAEY,QAAA,KAAK,GAAG,IAAI,aAAK,CAAC;IAC7B,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS;IAC1B,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW;CAC/B,CAAC,CAAC"}

package/dist/scripts/sync-api-keys.d.ts

@@ -0,0 +1,2 @@
+import 'dotenv/config';
+//# sourceMappingURL=sync-api-keys.d.ts.map

package/dist/scripts/sync-api-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-api-keys.d.ts","sourceRoot":"","sources":["../../src/scripts/sync-api-keys.ts"],"names":[],"mappings":"AAAA,OAAO,eAAe,CAAC"}

package/dist/scripts/sync-api-keys.js

@@ -0,0 +1,62 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
+const redis_1 = require("@upstash/redis");
+// Note: checking for properties on process.env needs type assertions or simply checking existence
+if (!process.env.REDIS_URL || !process.env.REDIS_TOKEN) {
+    throw new Error('Missing Upstash Redis credentials in .env file');
+}
+const redis = new redis_1.Redis({
+    url: process.env.REDIS_URL,
+    token: process.env.REDIS_TOKEN,
+});
+const KEY_SET = 'ru_api_keys';
+function syncApiKeys() {
+    return __awaiter(this, void 0, void 0, function* () {
+        console.log('Syncing API keys from RU_API_KEYS...');
+        const keysString = process.env.RU_API_KEYS || '';
+        const keysFromEnv = keysString.split(/[\n,]/).map(k => k.trim()).filter(Boolean);
+        if (keysFromEnv.length === 0) {
+            console.warn('No RU_API_KEYS found in environment variables.');
+            return;
+        }
+        const pipeline = redis.pipeline();
+        // Get existing keys
+        const keysInRedis = yield redis.zrange(KEY_SET, 0, -1);
+        // Determine additions and removals
+        const keysToAdd = keysFromEnv.filter(k => !keysInRedis.includes(k));
+        const keysToRemove = keysInRedis.filter(k => !keysFromEnv.includes(k));
+        if (keysToAdd.length > 0) {
+            console.log(`Adding ${keysToAdd.length} new keys.`);
+            for (const key of keysToAdd) {
+                // Add with score 0 (least used)
+                pipeline.zadd(KEY_SET, { score: 0, member: key });
+            }
+        }
+        if (keysToRemove.length > 0) {
+            console.log(`Removing ${keysToRemove.length} stale keys.`);
+            pipeline.zrem(KEY_SET, ...keysToRemove);
+        }
+        if (keysToAdd.length === 0 && keysToRemove.length === 0) {
+            console.log('Keys are already in sync.');
+        }
+        else {
+            yield pipeline.exec();
+            console.log('Sync complete.');
+        }
+    });
+}
+syncApiKeys().catch((err) => {
+    console.error('Error syncing keys:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=sync-api-keys.js.map

package/dist/scripts/sync-api-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-api-keys.js","sourceRoot":"","sources":["../../src/scripts/sync-api-keys.ts"],"names":[],"mappings":";;;;;;;;;;;AAAA,yBAAuB;AACvB,0CAAuC;AAEvC,kGAAkG;AAClG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;IACrD,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;AACtE,CAAC;AAED,MAAM,KAAK,GAAG,IAAI,aAAK,CAAC;IACpB,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,SAAS;IAC1B,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW;CACjC,CAAC,CAAC;AAEH,MAAM,OAAO,GAAG,aAAa,CAAC;AAE9B,SAAe,WAAW;;QACtB,OAAO,CAAC,GAAG,CAAC,sCAAsC,CAAC,CAAC;QAEpD,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC;QACjD,MAAM,WAAW,GAAG,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAEjF,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;YAC/D,OAAO;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC;QAElC,oBAAoB;QACpB,MAAM,WAAW,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAa,CAAC;QAEnE,mCAAmC;QACnC,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,MAAM,YAAY,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAEvE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,GAAG,CAAC,UAAU,SAAS,CAAC,MAAM,YAAY,CAAC,CAAC;YACpD,KAAK,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;gBAC1B,gCAAgC;gBAChC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;YACtD,CAAC;QACL,CAAC;QAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,GAAG,CAAC,YAAY,YAAY,CAAC,MAAM,cAAc,CAAC,CAAC;YAC3D,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,YAAY,CAAC,CAAC;QAC5C,CAAC;QAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtD,OAAO,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;QAC7C,CAAC;aAAM,CAAC;YACJ,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACtB,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAClC,CAAC;IACL,CAAC;CAAA;AAED,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACxB,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;IAC1C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "unlimit-keys",
+  "version": "0.1.0",
+  "description": "An API key rotation system using Redis",
+  "author": "Anirban Majumder <anirbanmajumder.404@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Anirban-Majumder/unlimit-keys.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Anirban-Majumder/unlimit-keys/issues"
+  },
+  "homepage": "https://github.com/Anirban-Majumder/unlimit-keys#readme",
+  "license": "MIT",
+  "keywords": [
+    "rate-limit",
+    "api-key",
+    "redis",
+    "upstash",
+    "key-rotation",
+    "lru",
+    "keys"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "unlimit-keys": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "sync": "node dist/scripts/sync-api-keys.js",
+    "test": "vitest run",
+    "publish-pkg": "npm publish --access public"
+  },
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@upstash/redis": ">=1.0.0",
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.15",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3",
+    "vitest": "^4.0.17"
+  },
+  "peerDependencies": {
+    "@upstash/redis": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@upstash/redis": {
+      "optional": true
+    }
+  }
+}