unlimit-keys 0.1.1 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anirban Majumder
+
+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

@@ -1,64 +1,204 @@
-# unlimit-keys
+# 🔑 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.).
+## **Never get blocked by rate limits again!** 
 
-## Installation
+Tired of hitting "Rate Limit Exceeded" errors? Use this tool to automatically rotate between your API keys. It picks the best key every time you make a request - so you can use AI services (Google Gemini, Groq, OpenAI, and more) without worrying about limits!
 
+## **What you get:**
+- 🚀 Use APIs 3x more (with 3 keys), 10x more (with 10 keys), etc.
+- 🔄 Automatic key rotation - no manual switching
+- ✅ Works with ANY API (AI, weather, payment, search, etc.)
+- ⚡ Super fast - handles thousands of requests per second
+- 🔒 Works perfectly with serverless apps and high-traffic services
+
+## Quick Start 🚀
+
+### Installation
+
+**Using npm:**
 ```bash
 npm install unlimit-keys
 ```
 
+**Using pnpm:**
+```bash
+pnpm add unlimit-keys
+```
+
 ## Setup
 
-### 1. Environment Variables
+### 1. Get Redis (Free!) 🗄️
+
+We use [Upstash Redis](https://upstash.com/) - it's free and perfect for this. Follow their setup guide to get your Redis URL and token.
 
-Create a `.env.local` file with your Redis credentials and API keys:
+Create a `.env.local` file with your keys:
 
 ```env
-# Upstash Redis credentials
+# Upstash Redis (get from https://upstash.com - it's free!)
 REDIS_URL=https://your-redis-url.upstash.io
 REDIS_TOKEN=your-token
 
-# Comma-separated or newline-separated API keys
+# Your API keys (comma or newline separated)
 API_KEYS="key1,key2,key3"
 ```
 
-### 2. Sync Keys to Redis
+### 2. Save Your Keys 📝
 
-Run the sync script to load your API keys into the global Redis pool:
+Run this once to save all your keys to Redis:
 
+**Using npm:**
 ```bash
 npx unlimit-keys sync
 ```
 
-## Usage
+**Using pnpm:**
+```bash
+pnpm dlx unlimit-keys sync
+```
+
+## How to Use It
 
-### Programmatic API
+### Option 1: In Your Code 💻
 
 ```typescript
 import { getLeastUsedKey } from 'unlimit-keys';
 
-// Get the least recently used key
+// Get the best key to use right now
 const apiKey = await getLeastUsedKey();
-console.log(apiKey);
+console.log("Using API Key:", apiKey);
+
+// Use it with your AI service
+const response = await fetch('https://api.example.com/chat', {
+  headers: { 'Authorization': \`Bearer \${apiKey}\` }
+});
 ```
 
-### CLI
+### Option 2: Command Line 📱
 
 ```bash
-# Get the least recently used key via CLI
 npx unlimit-keys get-key
 ```
 
-## How It Works
+## Real Examples 📚
+
+### Using with Google Gemini 🤖
+
+```typescript
+import { getLeastUsedKey } from 'unlimit-keys';
+
+async function askGemini(question: string) {
+  const apiKey = await getLeastUsedKey();
+  
+  const response = await fetch('https://generativelanguage.googleapis.com/v1beta/models/gemini-flash-latest:generateContent', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'x-goog-api-key': apiKey
+    },
+    body: JSON.stringify({
+      contents: [{ parts: [{ text: question }] }]
+    })
+  });
+  
+  return response.json();
+}
+
+// Use many times without rate limits!
+await askGemini('What is AI?');
+await askGemini('How do I code?');
+```
+
+### Using with Groq ⚡
+
+```typescript
+import { getLeastUsedKey } from 'unlimit-keys';
+import Groq from 'groq-sdk';
+
+async function askGroq(question: string) {
+  const apiKey = await getLeastUsedKey();
+  
+  const client = new Groq({ apiKey });
+  const message = await client.messages.create({
+    model: 'mixtral-8x7b-32768',
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: question }]
+  });
+  
+  return message;
+}
+
+await askGroq('Tell me a joke');
+```
+
+### Using with Google AI SDK 🎯
+
+```typescript
+import { getLeastUsedKey } from 'unlimit-keys';
+import { GoogleGenerativeAI } from '@google/generative-ai';
+
+async function askWithSDK(question: string) {
+  const apiKey = await getLeastUsedKey();
+  const genAI = new GoogleGenerativeAI(apiKey);
+  
+  const model = genAI.getGenerativeModel({ model: 'gemini-flash-latest' });
+  const result = await model.generateContent(question);
+  
+  return result.response.text();
+}
+
+await askWithSDK('What is machine learning?');
+```
+
+### Using with Regular APIs 🌍
+
+Not just for AI! Works with any API that uses keys. Here's an example with a weather API:
+
+```typescript
+import { getLeastUsedKey } from 'unlimit-keys';
+
+async function getWeather(city: string) {
+  const apiKey = await getLeastUsedKey();
+  
+  const response = await fetch(`https://api.openweathermap.org/data/2.5/weather?q=${city}&units=metric&appid=${apiKey}`, {
+    method: 'GET'
+  });
+  
+  return response.json();
+}
+
+// Make lots of weather requests without hitting rate limits!
+await getWeather('London');
+await getWeather('New York');
+await getWeather('Tokyo');
+```
+
+## Supported Services 🌐
+
+**AI & ML Services:**
+- 🤖 [Google Gemini](https://ai.google.dev/)
+- ⚡ [Groq](https://www.groq.com/)
+- 🧠 [OpenAI](https://openai.com/)
+- 🤖 [Anthropic Claude](https://www.anthropic.com/)
+
+**Other APIs:**
+- Weather APIs
+- Payment APIs
+- Search APIs
+- Translation APIs
+- And literally any API that uses keys!
+
+**Works with anything that has API rate limits!**
+
+## How It Works Behind the Scenes 🔧
+
+1. **You have multiple keys** - Like 3 API keys
+2. **We pick the best one** - We use the key that's been used the least recently
+3. **We use it** - You make your API call
+4. **We update the score** - We mark that key as just-used so we don't pick it again
+5. **Repeat!** - Next time you call us, we pick a different key
 
-1.  **Key Pool**: Keys are stored in a single Redis Sorted Set (`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.
+This spreads out your requests so you hit rate limits slower!
 
 ## License
 
-ISC
+MIT

package/dist/cli.js

@@ -17,7 +17,7 @@ const program = new commander_1.Command();
 program
     .name('unlimit-keys')
     .description('Distributed LRU API key rotation using Redis')
-    .version('0.1.5');
+    .version(require('../package.json').version);
 program
     .command('get-key')
     .description('Get the least recently used API key')

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;;;;;;;;AACA,yCAAoC;AACpC,8DAA2D;AAC3D,2DAAsD;AAEtD,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,8CAA8C,CAAC;KAC3D,MAAM,CAAC,GAAS,EAAE;IACjB,IAAI,CAAC;QACH,MAAM,IAAA,2BAAW,GAAE,CAAC;IACtB,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,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;;;;;;;;AACA,yCAAoC;AACpC,8DAA2D;AAC3D,2DAAsD;AAEtD,MAAM,OAAO,GAAG,IAAI,mBAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,cAAc,CAAC;KACpB,WAAW,CAAC,8CAA8C,CAAC;KAC3D,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,OAAO,CAAC,CAAC;AAE/C,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,8CAA8C,CAAC;KAC3D,MAAM,CAAC,GAAS,EAAE;IACjB,IAAI,CAAC;QACH,MAAM,IAAA,2BAAW,GAAE,CAAC;IACtB,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,CAAC,KAAK,EAAE,CAAC"}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "unlimit-keys",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "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"
+    "url": "git+https://github.com/Anirban-Majumder/unlimit-keys.git"
   },
   "bugs": {
     "url": "https://github.com/Anirban-Majumder/unlimit-keys/issues"
@@ -31,7 +31,7 @@
     }
   },
   "bin": {
-    "unlimit-keys": "./dist/cli.js"
+    "unlimit-keys": "dist/cli.js"
   },
   "files": [
     "dist"