octokit-load-balancer 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mert Ciflikli
+
+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,96 @@
+# octokit-load-balancer
+
+> Load balance across multiple GitHub App instances, always picking the one with most available rate limit
+
+[![npm version](https://img.shields.io/npm/v/octokit-load-balancer.svg)](https://www.npmjs.com/package/octokit-load-balancer)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## Features
+
+- **Multiple App Support** - Pool multiple GitHub Apps for higher aggregate rate limits
+- **Smart Selection** - Always picks the app with the most available rate limit
+- **Auto Key Detection** - Automatically detects raw PEM vs base64 encoded private keys
+- **TypeScript First** - Full type definitions using Octokit types
+- **Single Function API** - Just one function: `getApp`
+
+## Installation
+
+```bash
+npm install octokit-load-balancer octokit @octokit/auth-app
+```
+
+## Usage
+
+```typescript
+import { getApp } from 'octokit-load-balancer';
+
+const octokit = await getApp({
+  apps: [
+    {
+      appId: process.env.GH_APP_1_ID,
+      installationId: process.env.GH_APP_1_INSTALLATION_ID,
+      privateKey: process.env.GH_APP_1_KEY,
+    },
+    {
+      appId: process.env.GH_APP_2_ID,
+      installationId: process.env.GH_APP_2_INSTALLATION_ID,
+      privateKey: process.env.GH_APP_2_KEY,
+    },
+  ],
+  baseUrl: 'https://api.github.com',
+});
+
+await octokit.rest.repos.get({ owner: 'your-org', repo: 'your-repo' });
+```
+
+## How It Works
+
+Every time you call `getApp(config)`:
+
+1. Creates Octokit instances for all valid app configs
+2. Fetches rate limits for all apps in parallel
+3. Returns the Octokit with the highest remaining rate limit
+
+## Options
+
+| Option    | Type                | Required | Description                 |
+| --------- | ------------------- | -------- | --------------------------- |
+| `apps`    | `GitHubAppConfig[]` | Yes      | Array of app configurations |
+| `baseUrl` | `string`            | Yes      | GitHub API base URL         |
+
+App configs use `GitHubAppConfig` (re-exported from `@octokit/auth-app`'s `StrategyOptions`). All apps must have valid `appId` and `privateKey` — incomplete configs will throw an error.
+
+## Comparison with @octokit/plugin-throttling
+
+[`@octokit/plugin-throttling`](https://github.com/octokit/plugin-throttling.js) handles rate limits by queuing and retrying requests. This library takes a different approach: distribute load across multiple GitHub Apps to maximize available quota.
+
+|                    | octokit-load-balancer              | plugin-throttling         |
+| ------------------ | ---------------------------------- | ------------------------- |
+| Strategy           | Pick app with most remaining quota | Queue and retry on limits |
+| Multiple apps      | Yes                                | No                        |
+| Handles exhaustion | Throws                             | Waits and retries         |
+
+Choose based on your situation:
+
+- **Need more than 5000 requests/hour?** → Create multiple GitHub Apps and use this library to distribute load across them (N apps = N × 5000 req/hr)
+- **Single app, need graceful handling?** → Use plugin-throttling to wait and retry
+
+## Debugging
+
+Enable debug logs with the `DEBUG` environment variable:
+
+```bash
+DEBUG=octokit-load-balancer node your-script.js
+```
+
+Output:
+
+```
+[octokit-load-balancer] Using 2 valid app configs
+[octokit-load-balancer] Rate limits: app[0]: 4500/5000, app[1]: 4900/5000
+[octokit-load-balancer] Selected app[1] with 4900/5000 remaining
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,66 @@
+import { Octokit } from 'octokit';
+import { StrategyOptions } from '@octokit/auth-app';
+
+/**
+ * Configuration for a single GitHub App.
+ * Uses Octokit's StrategyOptions directly.
+ */
+type GitHubAppConfig = StrategyOptions;
+/**
+ * Rate limit data from GitHub API
+ */
+interface RateLimitData {
+    limit: number;
+    used: number;
+    remaining: number;
+    reset: number;
+}
+/**
+ * Configuration for getApp
+ */
+interface GitHubAppPoolConfig {
+    /** Array of app configurations */
+    apps: GitHubAppConfig[];
+    /** Base URL for the GitHub API (e.g., 'https://api.github.com' or 'https://github.company.com/api/v3') */
+    baseUrl: string;
+}
+/**
+ * Rate limit information for a GitHub App
+ */
+interface RateLimitInfo extends RateLimitData {
+    /** Index of the app in the config array */
+    appIndex: number;
+}
+
+/**
+ * Get the Octokit instance with the most available rate limit.
+ * Pass your app configurations directly - incomplete configs are filtered out.
+ *
+ * @example
+ * ```typescript
+ * import { getApp } from 'octokit-load-balancer'
+ *
+ * const octokit = await getApp({
+ *   apps: [
+ *     {
+ *       appId: process.env.APP_1_ID,
+ *       installationId: process.env.APP_1_INSTALLATION_ID,
+ *       privateKey: process.env.APP_1_KEY,
+ *     },
+ *     {
+ *       appId: process.env.APP_2_ID,
+ *       installationId: process.env.APP_2_INSTALLATION_ID,
+ *       privateKey: process.env.APP_2_KEY,
+ *     },
+ *   ],
+ *   baseUrl: 'https://github.example.com/api/v3',
+ * })
+ *
+ * await octokit.rest.repos.get({ owner: 'org', repo: 'repo' })
+ * ```
+ *
+ * @throws {Error} When no valid app configurations are provided
+ */
+declare function getApp(config: GitHubAppPoolConfig): Promise<Octokit>;
+
+export { type GitHubAppConfig, type GitHubAppPoolConfig, type RateLimitData, type RateLimitInfo, getApp };

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+import { Octokit } from 'octokit';
+import { StrategyOptions } from '@octokit/auth-app';
+
+/**
+ * Configuration for a single GitHub App.
+ * Uses Octokit's StrategyOptions directly.
+ */
+type GitHubAppConfig = StrategyOptions;
+/**
+ * Rate limit data from GitHub API
+ */
+interface RateLimitData {
+    limit: number;
+    used: number;
+    remaining: number;
+    reset: number;
+}
+/**
+ * Configuration for getApp
+ */
+interface GitHubAppPoolConfig {
+    /** Array of app configurations */
+    apps: GitHubAppConfig[];
+    /** Base URL for the GitHub API (e.g., 'https://api.github.com' or 'https://github.company.com/api/v3') */
+    baseUrl: string;
+}
+/**
+ * Rate limit information for a GitHub App
+ */
+interface RateLimitInfo extends RateLimitData {
+    /** Index of the app in the config array */
+    appIndex: number;
+}
+
+/**
+ * Get the Octokit instance with the most available rate limit.
+ * Pass your app configurations directly - incomplete configs are filtered out.
+ *
+ * @example
+ * ```typescript
+ * import { getApp } from 'octokit-load-balancer'
+ *
+ * const octokit = await getApp({
+ *   apps: [
+ *     {
+ *       appId: process.env.APP_1_ID,
+ *       installationId: process.env.APP_1_INSTALLATION_ID,
+ *       privateKey: process.env.APP_1_KEY,
+ *     },
+ *     {
+ *       appId: process.env.APP_2_ID,
+ *       installationId: process.env.APP_2_INSTALLATION_ID,
+ *       privateKey: process.env.APP_2_KEY,
+ *     },
+ *   ],
+ *   baseUrl: 'https://github.example.com/api/v3',
+ * })
+ *
+ * await octokit.rest.repos.get({ owner: 'org', repo: 'repo' })
+ * ```
+ *
+ * @throws {Error} When no valid app configurations are provided
+ */
+declare function getApp(config: GitHubAppPoolConfig): Promise<Octokit>;
+
+export { type GitHubAppConfig, type GitHubAppPoolConfig, type RateLimitData, type RateLimitInfo, getApp };

package/dist/index.js

@@ -0,0 +1,114 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  getApp: () => getApp
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/pool.ts
+var import_auth_app = require("@octokit/auth-app");
+var import_octokit = require("octokit");
+var DEBUG_KEY = "octokit-load-balancer";
+async function getApp(config) {
+  if (!Array.isArray(config?.apps)) {
+    throw new Error("Invalid config: apps must be an array");
+  }
+  if (typeof config?.baseUrl !== "string") {
+    throw new Error("Invalid config: baseUrl must be a string");
+  }
+  if (config.apps.length === 0) {
+    throw new Error("Invalid config: apps array is empty");
+  }
+  const invalidApps = config.apps.filter((app) => !isCompleteConfig(app));
+  if (invalidApps.length > 0) {
+    throw new Error(
+      `Invalid config: ${invalidApps.length} app(s) missing required appId or privateKey`
+    );
+  }
+  const validApps = config.apps;
+  log(`Using ${validApps.length} valid app configs`);
+  const octokits = validApps.map((app) => createOctokit(app, config.baseUrl));
+  const rateLimits = await Promise.all(
+    octokits.map((o, i) => getRateLimit(o, i))
+  );
+  log(
+    "Rate limits:",
+    rateLimits.map((r) => `app[${r.appIndex}]: ${r.remaining}/${r.limit}`).join(", ")
+  );
+  const { bestIndex, rateLimit } = rateLimits.reduce(
+    (acc, cur, i) => {
+      if (cur.remaining > acc.rateLimit.remaining) {
+        return { bestIndex: i, rateLimit: cur };
+      }
+      return acc;
+    },
+    { bestIndex: 0, rateLimit: rateLimits[0] }
+  );
+  if (rateLimit.remaining === 0) {
+    throw new Error("All GitHub Apps have exhausted their rate limits");
+  }
+  log(
+    `Selected app[${bestIndex}] with ${rateLimit.remaining}/${rateLimit.limit} remaining`
+  );
+  return octokits[bestIndex];
+}
+function isCompleteConfig(config) {
+  return typeof config === "object" && config !== null && "appId" in config && "privateKey" in config && !!(config.appId && config.privateKey);
+}
+function decodePrivateKey(key) {
+  if (key.startsWith("-----BEGIN ") && key.includes("-----END ")) {
+    return key;
+  }
+  return Buffer.from(key, "base64").toString("utf-8");
+}
+function createOctokit(appConfig, baseUrl) {
+  return new import_octokit.Octokit({
+    authStrategy: import_auth_app.createAppAuth,
+    baseUrl: baseUrl || "https://api.github.com",
+    auth: {
+      appId: appConfig.appId,
+      installationId: appConfig.installationId,
+      privateKey: decodePrivateKey(appConfig.privateKey)
+    }
+  });
+}
+async function getRateLimit(octokit, index) {
+  const response = await octokit.rest.rateLimit.get();
+  return {
+    ...response.data.rate,
+    appIndex: index
+  };
+}
+function isDebugEnabled() {
+  const debug = process.env.DEBUG;
+  if (!debug) return false;
+  return debug === "*" || debug.includes(DEBUG_KEY);
+}
+function log(...args) {
+  if (isDebugEnabled()) {
+    console.log(`[${DEBUG_KEY}]`, ...args);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getApp
+});

package/dist/index.mjs

@@ -0,0 +1,87 @@
+// src/pool.ts
+import { createAppAuth } from "@octokit/auth-app";
+import { Octokit } from "octokit";
+var DEBUG_KEY = "octokit-load-balancer";
+async function getApp(config) {
+  if (!Array.isArray(config?.apps)) {
+    throw new Error("Invalid config: apps must be an array");
+  }
+  if (typeof config?.baseUrl !== "string") {
+    throw new Error("Invalid config: baseUrl must be a string");
+  }
+  if (config.apps.length === 0) {
+    throw new Error("Invalid config: apps array is empty");
+  }
+  const invalidApps = config.apps.filter((app) => !isCompleteConfig(app));
+  if (invalidApps.length > 0) {
+    throw new Error(
+      `Invalid config: ${invalidApps.length} app(s) missing required appId or privateKey`
+    );
+  }
+  const validApps = config.apps;
+  log(`Using ${validApps.length} valid app configs`);
+  const octokits = validApps.map((app) => createOctokit(app, config.baseUrl));
+  const rateLimits = await Promise.all(
+    octokits.map((o, i) => getRateLimit(o, i))
+  );
+  log(
+    "Rate limits:",
+    rateLimits.map((r) => `app[${r.appIndex}]: ${r.remaining}/${r.limit}`).join(", ")
+  );
+  const { bestIndex, rateLimit } = rateLimits.reduce(
+    (acc, cur, i) => {
+      if (cur.remaining > acc.rateLimit.remaining) {
+        return { bestIndex: i, rateLimit: cur };
+      }
+      return acc;
+    },
+    { bestIndex: 0, rateLimit: rateLimits[0] }
+  );
+  if (rateLimit.remaining === 0) {
+    throw new Error("All GitHub Apps have exhausted their rate limits");
+  }
+  log(
+    `Selected app[${bestIndex}] with ${rateLimit.remaining}/${rateLimit.limit} remaining`
+  );
+  return octokits[bestIndex];
+}
+function isCompleteConfig(config) {
+  return typeof config === "object" && config !== null && "appId" in config && "privateKey" in config && !!(config.appId && config.privateKey);
+}
+function decodePrivateKey(key) {
+  if (key.startsWith("-----BEGIN ") && key.includes("-----END ")) {
+    return key;
+  }
+  return Buffer.from(key, "base64").toString("utf-8");
+}
+function createOctokit(appConfig, baseUrl) {
+  return new Octokit({
+    authStrategy: createAppAuth,
+    baseUrl: baseUrl || "https://api.github.com",
+    auth: {
+      appId: appConfig.appId,
+      installationId: appConfig.installationId,
+      privateKey: decodePrivateKey(appConfig.privateKey)
+    }
+  });
+}
+async function getRateLimit(octokit, index) {
+  const response = await octokit.rest.rateLimit.get();
+  return {
+    ...response.data.rate,
+    appIndex: index
+  };
+}
+function isDebugEnabled() {
+  const debug = process.env.DEBUG;
+  if (!debug) return false;
+  return debug === "*" || debug.includes(DEBUG_KEY);
+}
+function log(...args) {
+  if (isDebugEnabled()) {
+    console.log(`[${DEBUG_KEY}]`, ...args);
+  }
+}
+export {
+  getApp
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "octokit-load-balancer",
+  "version": "1.0.1",
+  "description": "Load balance across multiple GitHub App instances, always picking the one with most available rate limit",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "publish:jsr": "npx jsr publish"
+  },
+  "keywords": [
+    "github",
+    "github-app",
+    "octokit",
+    "rate-limit",
+    "load-balancing",
+    "load-balancer",
+    "api"
+  ],
+  "author": "Mert Ciflikli",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/frankie303/octokit-load-balancer/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/frankie303/octokit-load-balancer"
+  },
+  "peerDependencies": {
+    "@octokit/auth-app": "^7.0.0",
+    "octokit": "^5.0.0"
+  },
+  "devDependencies": {
+    "@octokit/auth-app": "^7.2.2",
+    "@types/node": "^20.19.28",
+    "@vitest/coverage-v8": "^4.0.17",
+    "octokit": "^5.0.5",
+    "prettier": "^3.7.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}