insta-checker-sdk 1.0.0 → 1.0.3

package/README.md

@@ -0,0 +1,116 @@
+# Insta Checker SDK
+
+A Node.js and TypeScript library to check if an Instagram username is available. It handles connection pooling, caching, and retries so you don't have to write that boilerplate yourself.
+
+This is useful for Discord bots, web apps, or scripts that need to check a lot of names quickly.
+
+## Installation
+
+Install the package via npm:
+
+```bash
+npm install insta-checker-sdk
+```
+
+## Quick Start
+
+Here is the simplest way to check one username.
+
+```javascript
+const InstaChecker = require('insta-checker-sdk');
+
+const checker = new InstaChecker();
+
+async function run() {
+    const result = await checker.checkUsername('ninja');
+    
+    if (result.available) {
+        console.log('The username is free.');
+    } else {
+        console.log('The username is taken.');
+    }
+}
+
+run();
+```
+
+## Features
+
+*   **Connection Pooling**: Reuses HTTP connections to check names faster.
+*   **Caching**: Saves results in memory for a set time to avoid checking the same name twice.
+*   **Retries**: Automatically tries again if a request times out or fails.
+*   **Batch Checking**: Checks multiple names in parallel with a configurable limit.
+*   **TypeScript Support**: Included types for full IDE autocomplete.
+
+## Basic Usage
+
+### Checking a single username
+
+The `checkUsername` method returns an object with two properties: `available` (boolean) and `cached` (boolean).
+
+```javascript
+const InstaChecker = require('insta-checker-sdk');
+const checker = new InstaChecker({ timeout: 3000 });
+
+const result = await checker.checkUsername('apple');
+
+console.log(result);
+// Output: { available: false, cached: false }
+```
+
+### Checking multiple usernames
+
+Use `checkBatch` to process a list of names. This runs checks in parallel based on your concurrency setting.
+
+```javascript
+const usernames = ['john', 'jane', 'doe', 'admin'];
+
+const results = await checker.checkBatch(usernames);
+
+console.log(results);
+// Output: { john: false, jane: true, doe: true, admin: false }
+```
+
+You can add a callback to track progress while the batch is running.
+
+```javascript
+await checker.checkBatch(usernames, {
+    onProgress: (info) => {
+        console.log(`Checked ${info.current} of ${info.total}`);
+    }
+});
+```
+
+## Configuration
+
+You can pass an options object to the constructor.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `timeout` | number | 5000 | Time to wait for a response in milliseconds. |
+| `concurrency` | number | 5 | How many requests to send at the same time. |
+| `retries` | number | 2 | How many times to retry a failed request. |
+| `cacheTTL` | number | 300000 | How long to cache results in milliseconds (default 5 mins). |
+| `enableCache` | boolean | true | Turn caching on or off. |
+
+Example:
+
+```javascript
+const checker = new InstaChecker({
+    concurrency: 10, // Check 10 names at once
+    timeout: 2000,  // Fail fast after 2 seconds
+    cacheTTL: 60000 // Keep cache for 1 minute
+});
+```
+
+## Clearing Cache
+
+If you want to force a refresh of all names, clear the cache manually.
+
+```javascript
+checker.clearCache();
+```
+
+## License
+
+MIT

package/docs/api-reference.md

@@ -0,0 +1,90 @@
+# API Reference
+
+This is a detailed list of the methods and options available in the SDK.
+
+## Class: InstaChecker
+
+### Constructor
+
+```typescript
+new InstaChecker(options?)
+```
+
+Creates a new checker instance.
+
+**Parameters:**
+
+*   `options` (Object): Optional configuration object.
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `timeout` | number | 5000 | Request timeout in ms. |
+| `concurrency` | number | 5 | Number of parallel requests allowed. |
+| `retries` | number | 2 | Number of times to retry a failed request. |
+| `cacheTTL` | number | 300000 | Cache time to live in ms. |
+| `enableCache` | boolean | true | Enable or disable the memory cache. |
+
+### Method: checkUsername
+
+Checks if a single username is available.
+
+```typescript
+checkUsername(username: string): Promise<CheckResult>
+```
+
+**Parameters:**
+
+*   `username` (string): The Instagram username to check.
+
+**Returns:**
+
+A Promise that resolves to a `CheckResult` object:
+
+```typescript
+{
+    available: boolean, // true if available, false if taken
+    cached: boolean     // true if result came from memory cache
+}
+```
+
+**Throws:**
+
+Throws an Error if the username is invalid or if the request fails after all retries.
+
+### Method: checkBatch
+
+Checks multiple usernames in parallel.
+
+```typescript
+checkBatch(usernames: string[], options?: BatchOptions): Promise<Record<string, boolean | null>>
+```
+
+**Parameters:**
+
+*   `usernames` (string[]): An array of username strings.
+*   `options` (Object): Optional settings.
+    *   `onProgress` (function): A callback function that fires every time a username finishes.
+
+**Returns:**
+
+A Promise that resolves to an object where keys are usernames and values are booleans (`true`, `false`) or `null` if an error occurred.
+
+**Example:**
+
+```javascript
+const results = await checker.checkBatch(['a', 'b', 'c'], {
+    onProgress: (info) => {
+        console.log(`${info.current}/${info.total} done`);
+    }
+});
+```
+
+### Method: clearCache
+
+Clears all items from the in-memory cache.
+
+```typescript
+clearCache(): void
+```
+
+Use this if you want to ensure all subsequent checks hit the live API.

package/docs/examples.md

@@ -0,0 +1,127 @@
+# Usage Examples
+
+Here are some common patterns for using this SDK in different types of applications.
+
+## Discord Bot (discord.js)
+
+This example shows how to add a command to check a username.
+
+```javascript
+const { Client, GatewayIntentBits } = require('discord.js');
+const InstaChecker = require('insta-checker-sdk');
+
+// Initialize the checker
+const checker = new InstaChecker({ timeout: 5000 });
+
+const client = new Client({ intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages] });
+
+client.on('messageCreate', async message => {
+    if (message.content.startsWith('!check')) {
+        // Get the username from the command
+        const args = message.content.split(' ');
+        const username = args[1];
+
+        if (!username) {
+            return message.reply('Please provide a username.');
+        }
+
+        // Reply immediately so the user knows we are working
+        const msg = await message.channel.send(`Checking \`${username}\`...`);
+
+        try {
+            const result = await checker.checkUsername(username);
+            
+            let status = result.available ? 'Available' : 'Taken';
+            if (result.cached) status += ' (Cached)';
+            
+            msg.edit(`Status: ${status}`);
+        } catch (error) {
+            msg.edit('Error checking username.');
+        }
+    }
+});
+
+client.login('YOUR_BOT_TOKEN');
+```
+
+## Express Web API
+
+This example creates a simple HTTP endpoint to check usernames.
+
+```javascript
+const express = require('express');
+const InstaChecker = require('insta-checker-sdk');
+
+const app = express();
+const checker = new InstaChecker({ concurrency: 20 });
+
+// Middleware to parse JSON
+app.use(express.json());
+
+app.get('/api/check/:username', async (req, res) => {
+    const { username } = req.params;
+
+    try {
+        const result = await checker.checkUsername(username);
+        res.json({
+            username: username,
+            available: result.available,
+            cached: result.cached
+        });
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.post('/api/check-batch', async (req, res) => {
+    const { usernames } = req.body;
+
+    if (!Array.isArray(usernames)) {
+        return res.status(400).json({ error: 'Expected an array of usernames' });
+    }
+
+    try {
+        const results = await checker.checkBatch(usernames);
+        res.json(results);
+    } catch (err) {
+        res.status(500).json({ error: err.message });
+    }
+});
+
+app.listen(3000, () => console.log('Server running on port 3000'));
+```
+
+## Bulk Checking with Progress
+
+If you need to check 10,000 usernames, you might want to log progress to the console.
+
+```javascript
+const InstaChecker = require('insta-checker-sdk');
+const fs = require('fs');
+
+const checker = new InstaChecker({ concurrency: 10 });
+
+// Imagine you loaded this from a file
+const hugeList = Array.from({ length: 1000 }, (_, i) => `user${i}`);
+
+async function runBulk() {
+    console.log(`Starting bulk check for ${hugeList.length} users...`);
+
+    const startTime = Date.now();
+
+    const results = await checker.checkBatch(hugeList, {
+        onProgress: (info) => {
+            // Update console log in place
+            process.stdout.write(`\rProgress: ${info.current}/${info.total} (${Math.round(info.current/info.total*100)}%)`);
+        }
+    });
+
+    const duration = (Date.now() - startTime) / 1000;
+    console.log(`\nDone in ${duration} seconds.`);
+
+    // Save to file
+    fs.writeFileSync('results.json', JSON.stringify(results, null, 2));
+}
+
+runBulk();
+```

package/docs/getting-started.md

@@ -0,0 +1,77 @@
+
+# Getting Started
+
+This guide covers the basics of setting up and running the Insta Checker SDK in your project.
+
+## How it works
+
+The library uses an external API to check availability. It sends a POST request and looks for the `available` status in the response.
+
+To make this efficient for production, we do a few things:
+
+1.  **Keep-Alive**: We open an HTTPS connection and keep it open to check many names without reconnecting.
+2.  **Concurrency**: We don't fire off 1000 requests instantly. We queue them and process them in small batches (default is 5 at a time).
+3.  **Memory Cache**: If you check "instagram" twice in 5 minutes, the second time comes from memory.
+
+## Installation
+
+Make sure you are using Node.js version 14 or higher.
+
+```bash
+npm install insta-checker-sdk
+```
+## Your first script
+
+Create a file called `check.js` and paste this code:
+
+```javascript
+const InstaChecker = require('insta-checker-sdk');
+
+// Create a new instance
+const checker = new InstaChecker({
+    timeout: 5000,
+    retries: 3
+});
+
+async function main() {
+    try {
+        console.log('Checking username...');
+        const result = await checker.checkUsername('microsoft');
+        
+        if (result.available) {
+            console.log('Available!');
+        } else {
+            console.log('Taken.');
+        }
+    } catch (error) {
+        console.error('Something went wrong:', error.message);
+    }
+}
+
+main();
+```
+
+Run it:
+
+```bash
+node check.js
+```
+
+## TypeScript Support
+
+If you use TypeScript, import the class and the types.
+
+```typescript
+import InstaChecker, { CheckerOptions, CheckResult } from 'insta-checker-sdk';
+
+const options: CheckerOptions = {
+    timeout: 4000
+};
+
+const checker = new InstaChecker(options);
+
+const result: CheckResult = await checker.checkUsername('google');
+```
+
+The types are built into the package, so you don't need to install anything extra.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "insta-checker-sdk",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "A robust, production-ready Instagram username availability checker written in TypeScript.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -34,6 +34,7 @@
   },
   "files": [
     "dist/",
+    "docs/",
     "README.md",
     "LICENSE"
   ]