mcp-docs-scraper 0.1.0

package/dist/types/errors.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Custom error types for MCP Docs Scraper.
+ *
+ * All errors extend DocsError for consistent handling.
+ */
+/**
+ * Error codes for categorizing errors.
+ */
+export type DocsErrorCode = "INVALID_URL" | "GITHUB_RATE_LIMIT" | "GITHUB_NOT_FOUND" | "GITHUB_ACCESS_DENIED" | "CACHE_NOT_FOUND" | "SCRAPING_BLOCKED" | "NO_CONTENT" | "NETWORK_ERROR" | "PARSE_ERROR" | "VALIDATION_ERROR" | "UNKNOWN_ERROR";
+/**
+ * Base error class for all documentation-related errors.
+ * Provides structured error information for agents.
+ */
+export declare class DocsError extends Error {
+    /** Error code for categorization */
+    readonly code: DocsErrorCode;
+    /** User-friendly message */
+    readonly userMessage: string;
+    /** Recovery suggestions */
+    readonly suggestions: string[];
+    /** Additional context */
+    readonly context?: Record<string, unknown>;
+    constructor(code: DocsErrorCode, message: string, options?: {
+        userMessage?: string;
+        suggestions?: string[];
+        context?: Record<string, unknown>;
+        cause?: Error;
+    });
+    /**
+     * Converts the error to a structured object for MCP responses.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error for invalid URLs.
+ */
+export declare class InvalidUrlError extends DocsError {
+    constructor(url: string, reason?: string);
+}
+/**
+ * Error for GitHub rate limit exceeded.
+ */
+export declare class GitHubRateLimitError extends DocsError {
+    constructor(resetTime?: Date);
+}
+/**
+ * Error for GitHub repository not found.
+ */
+export declare class GitHubNotFoundError extends DocsError {
+    constructor(repo: string);
+}
+/**
+ * Error for GitHub access denied (private repo).
+ */
+export declare class GitHubAccessDeniedError extends DocsError {
+    constructor(repo: string);
+}
+/**
+ * Error for cache entry not found.
+ */
+export declare class CacheNotFoundError extends DocsError {
+    constructor(docsId: string);
+}
+/**
+ * Error for scraping blocked.
+ */
+export declare class ScrapingBlockedError extends DocsError {
+    constructor(url: string, reason?: string);
+}
+/**
+ * Error for no content found.
+ */
+export declare class NoContentError extends DocsError {
+    constructor(url: string);
+}
+/**
+ * Error for network failures.
+ */
+export declare class NetworkError extends DocsError {
+    constructor(url: string, cause?: Error);
+}
+/**
+ * Error for validation failures.
+ */
+export declare class ValidationError extends DocsError {
+    constructor(message: string, field?: string);
+}
+/**
+ * Wraps an unknown error in a DocsError.
+ */
+export declare function wrapError(error: unknown, context?: string): DocsError;
+/**
+ * Creates a structured error response for MCP tools.
+ */
+export declare function createErrorResponse(error: unknown): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,aAAa,GACb,mBAAmB,GACnB,kBAAkB,GAClB,sBAAsB,GACtB,iBAAiB,GACjB,kBAAkB,GAClB,YAAY,GACZ,eAAe,GACf,aAAa,GACb,kBAAkB,GAClB,eAAe,CAAC;AAEpB;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,4BAA4B;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2BAA2B;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAC/B,yBAAyB;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGzC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,KAAK,CAAC,EAAE,KAAK,CAAC;KACV;IAUR;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CASlC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAWzC;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,SAAS,CAAC,EAAE,IAAI;CAiB7B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,IAAI,EAAE,MAAM;CAWzB;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;gBACxC,IAAI,EAAE,MAAM;CAWzB;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,SAAS;gBACnC,MAAM,EAAE,MAAM;CAW3B;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAWzC;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,SAAS;gBAC/B,GAAG,EAAE,MAAM;CAWxB;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,SAAS;gBAC7B,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAYvC;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBAChC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM;CAO5C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAarE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG;IACnD,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,IAAI,CAAC;CACf,CAYA"}

package/dist/types/errors.js

@@ -0,0 +1,216 @@
+/**
+ * Custom error types for MCP Docs Scraper.
+ *
+ * All errors extend DocsError for consistent handling.
+ */
+/**
+ * Base error class for all documentation-related errors.
+ * Provides structured error information for agents.
+ */
+export class DocsError extends Error {
+    /** Error code for categorization */
+    code;
+    /** User-friendly message */
+    userMessage;
+    /** Recovery suggestions */
+    suggestions;
+    /** Additional context */
+    context;
+    constructor(code, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = "DocsError";
+        this.code = code;
+        this.userMessage = options.userMessage || message;
+        this.suggestions = options.suggestions || [];
+        this.context = options.context;
+    }
+    /**
+     * Converts the error to a structured object for MCP responses.
+     */
+    toJSON() {
+        return {
+            error: true,
+            code: this.code,
+            message: this.userMessage,
+            suggestions: this.suggestions.length > 0 ? this.suggestions : undefined,
+            context: this.context,
+        };
+    }
+}
+/**
+ * Error for invalid URLs.
+ */
+export class InvalidUrlError extends DocsError {
+    constructor(url, reason) {
+        super("INVALID_URL", `Invalid URL: ${url}${reason ? ` - ${reason}` : ""}`, {
+            userMessage: "Could not access URL. Check the URL is correct and accessible.",
+            suggestions: [
+                "Verify the URL is spelled correctly",
+                "Ensure the URL includes the protocol (https://)",
+                "Check if the website is accessible in a browser",
+            ],
+            context: { url, reason },
+        });
+    }
+}
+/**
+ * Error for GitHub rate limit exceeded.
+ */
+export class GitHubRateLimitError extends DocsError {
+    constructor(resetTime) {
+        const resetIn = resetTime
+            ? Math.ceil((resetTime.getTime() - Date.now()) / 60000)
+            : undefined;
+        super("GITHUB_RATE_LIMIT", "GitHub API rate limit exceeded", {
+            userMessage: resetIn
+                ? `GitHub API rate limit reached. Try again in ${resetIn} minutes or use scraping fallback.`
+                : "GitHub API rate limit reached. Try again later or use scraping fallback.",
+            suggestions: [
+                'Use type: "scrape" to fetch via web scraping instead',
+                "Set GITHUB_TOKEN environment variable for higher rate limits (5000/hour)",
+                "Wait for the rate limit to reset",
+            ],
+            context: { resetTime: resetTime?.toISOString(), resetInMinutes: resetIn },
+        });
+    }
+}
+/**
+ * Error for GitHub repository not found.
+ */
+export class GitHubNotFoundError extends DocsError {
+    constructor(repo) {
+        super("GITHUB_NOT_FOUND", `GitHub repository not found: ${repo}`, {
+            userMessage: `Repository "${repo}" not found on GitHub.`,
+            suggestions: [
+                "Check if the repository name is spelled correctly",
+                "Verify the repository exists and is public",
+                "Use the full URL format: https://github.com/owner/repo",
+            ],
+            context: { repo },
+        });
+    }
+}
+/**
+ * Error for GitHub access denied (private repo).
+ */
+export class GitHubAccessDeniedError extends DocsError {
+    constructor(repo) {
+        super("GITHUB_ACCESS_DENIED", `Access denied to repository: ${repo}`, {
+            userMessage: `Cannot access repository "${repo}". It may be private or restricted.`,
+            suggestions: [
+                "Ensure the repository is public",
+                "Set GITHUB_TOKEN with appropriate permissions",
+                'Use type: "scrape" if documentation is available on a public website',
+            ],
+            context: { repo },
+        });
+    }
+}
+/**
+ * Error for cache entry not found.
+ */
+export class CacheNotFoundError extends DocsError {
+    constructor(docsId) {
+        super("CACHE_NOT_FOUND", `Documentation not found in cache: ${docsId}`, {
+            userMessage: `Documentation "${docsId}" not found in cache.`,
+            suggestions: [
+                "Run index_docs first to fetch and cache the documentation",
+                "Use list_cached_docs to see available cached documentation",
+                "Check if the docs_id is spelled correctly",
+            ],
+            context: { docsId },
+        });
+    }
+}
+/**
+ * Error for scraping blocked.
+ */
+export class ScrapingBlockedError extends DocsError {
+    constructor(url, reason) {
+        super("SCRAPING_BLOCKED", `Scraping blocked for ${url}`, {
+            userMessage: "Website blocked automated access.",
+            suggestions: [
+                "Try using a GitHub repository URL if available",
+                "Use detect_github_repo to find the source repository",
+                "The website may require authentication or block bots",
+            ],
+            context: { url, reason },
+        });
+    }
+}
+/**
+ * Error for no content found.
+ */
+export class NoContentError extends DocsError {
+    constructor(url) {
+        super("NO_CONTENT", `No documentation content found at ${url}`, {
+            userMessage: "No documentation content found at this URL.",
+            suggestions: [
+                "Try a different starting URL (e.g., /docs or /documentation)",
+                "Increase the crawl depth if content is nested",
+                "Check if the URL returns actual documentation content",
+            ],
+            context: { url },
+        });
+    }
+}
+/**
+ * Error for network failures.
+ */
+export class NetworkError extends DocsError {
+    constructor(url, cause) {
+        super("NETWORK_ERROR", `Network error accessing ${url}`, {
+            userMessage: "Could not connect to the server. Check your network connection.",
+            suggestions: [
+                "Verify your internet connection",
+                "Check if the website is online",
+                "Try again in a few moments",
+            ],
+            context: { url },
+            cause,
+        });
+    }
+}
+/**
+ * Error for validation failures.
+ */
+export class ValidationError extends DocsError {
+    constructor(message, field) {
+        super("VALIDATION_ERROR", message, {
+            userMessage: message,
+            suggestions: ["Check the input parameters", "Refer to the tool description for required fields"],
+            context: { field },
+        });
+    }
+}
+/**
+ * Wraps an unknown error in a DocsError.
+ */
+export function wrapError(error, context) {
+    if (error instanceof DocsError) {
+        return error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const cause = error instanceof Error ? error : undefined;
+    return new DocsError("UNKNOWN_ERROR", context ? `${context}: ${message}` : message, {
+        userMessage: "An unexpected error occurred.",
+        suggestions: ["Try the operation again", "Check the input parameters"],
+        cause,
+    });
+}
+/**
+ * Creates a structured error response for MCP tools.
+ */
+export function createErrorResponse(error) {
+    const docsError = error instanceof DocsError ? error : wrapError(error);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(docsError.toJSON(), null, 2),
+            },
+        ],
+        isError: true,
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/types/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/types/errors.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared types - re-exports from domain-specific type files.
+ */
+export type { DocsTreeNode, CacheMeta, CacheEntrySummary, } from "./cache.js";
+export { DocsError, InvalidUrlError, GitHubRateLimitError, GitHubNotFoundError, GitHubAccessDeniedError, CacheNotFoundError, ScrapingBlockedError, NoContentError, NetworkError, ValidationError, wrapError, createErrorResponse, type DocsErrorCode, } from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,YAAY,EACZ,SAAS,EACT,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,SAAS,EACT,mBAAmB,EACnB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,5 @@
+/**
+ * Shared types - re-exports from domain-specific type files.
+ */
+export { DocsError, InvalidUrlError, GitHubRateLimitError, GitHubNotFoundError, GitHubAccessDeniedError, CacheNotFoundError, ScrapingBlockedError, NoContentError, NetworkError, ValidationError, wrapError, createErrorResponse, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,OAAO,EACL,SAAS,EACT,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,SAAS,EACT,mBAAmB,GAEpB,MAAM,aAAa,CAAC"}

package/dist/utils/fs.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Default cache directory location.
+ */
+export declare const CACHE_DIR: string;
+/**
+ * Ensures a directory exists, creating it and parents if needed.
+ */
+export declare function ensureDir(dirPath: string): Promise<void>;
+/**
+ * Ensures parent directory exists before writing a file.
+ */
+export declare function ensureParentDir(filePath: string): Promise<void>;
+/**
+ * Reads a JSON file and parses it.
+ * Returns null if file doesn't exist.
+ */
+export declare function readJson<T>(filePath: string): Promise<T | null>;
+/**
+ * Writes an object as JSON to a file, creating parent dirs if needed.
+ */
+export declare function writeJson<T>(filePath: string, data: T): Promise<void>;
+/**
+ * Reads a text file.
+ * Returns null if file doesn't exist.
+ */
+export declare function readText(filePath: string): Promise<string | null>;
+/**
+ * Writes text to a file, creating parent dirs if needed.
+ */
+export declare function writeText(filePath: string, content: string): Promise<void>;
+/**
+ * Removes a file or directory recursively.
+ * Does nothing if path doesn't exist.
+ */
+export declare function remove(targetPath: string): Promise<void>;
+/**
+ * Lists immediate subdirectories in a directory.
+ * Returns empty array if directory doesn't exist.
+ */
+export declare function listDirectories(dirPath: string): Promise<string[]>;
+/**
+ * Checks if a path exists.
+ */
+export declare function exists(targetPath: string): Promise<boolean>;
+//# sourceMappingURL=fs.d.ts.map

package/dist/utils/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/utils/fs.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,eAAO,MAAM,SAAS,QAAqC,CAAC;AAE5D;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErE;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAUrE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3E;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASvE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhF;AAED;;;GAGG;AACH,wBAAsB,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAS9D;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAYxE;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUjE"}

package/dist/utils/fs.js

@@ -0,0 +1,113 @@
+import { mkdir, readFile, writeFile, rm, readdir, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+/**
+ * Default cache directory location.
+ */
+export const CACHE_DIR = join(homedir(), ".mcp-docs-cache");
+/**
+ * Ensures a directory exists, creating it and parents if needed.
+ */
+export async function ensureDir(dirPath) {
+    await mkdir(dirPath, { recursive: true });
+}
+/**
+ * Ensures parent directory exists before writing a file.
+ */
+export async function ensureParentDir(filePath) {
+    await ensureDir(dirname(filePath));
+}
+/**
+ * Reads a JSON file and parses it.
+ * Returns null if file doesn't exist.
+ */
+export async function readJson(filePath) {
+    try {
+        const content = await readFile(filePath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Writes an object as JSON to a file, creating parent dirs if needed.
+ */
+export async function writeJson(filePath, data) {
+    await ensureParentDir(filePath);
+    await writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
+}
+/**
+ * Reads a text file.
+ * Returns null if file doesn't exist.
+ */
+export async function readText(filePath) {
+    try {
+        return await readFile(filePath, "utf-8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Writes text to a file, creating parent dirs if needed.
+ */
+export async function writeText(filePath, content) {
+    await ensureParentDir(filePath);
+    await writeFile(filePath, content, "utf-8");
+}
+/**
+ * Removes a file or directory recursively.
+ * Does nothing if path doesn't exist.
+ */
+export async function remove(targetPath) {
+    try {
+        await rm(targetPath, { recursive: true, force: true });
+    }
+    catch (error) {
+        // Ignore if already doesn't exist
+        if (error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+}
+/**
+ * Lists immediate subdirectories in a directory.
+ * Returns empty array if directory doesn't exist.
+ */
+export async function listDirectories(dirPath) {
+    try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * Checks if a path exists.
+ */
+export async function exists(targetPath) {
+    try {
+        await stat(targetPath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=fs.js.map

package/dist/utils/fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.js","sourceRoot":"","sources":["../../src/utils/fs.ts"],"names":[],"mappings":"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"}

package/dist/utils/rate-limit.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Rate limit tracker for GitHub API.
+ */
+export interface RateLimitInfo {
+    /** Maximum requests allowed per hour */
+    limit: number;
+    /** Remaining requests in current window */
+    remaining: number;
+    /** Unix timestamp when rate limit resets */
+    reset: number;
+    /** When this info was last updated */
+    updatedAt: Date;
+}
+/**
+ * Tracks GitHub API rate limits.
+ */
+export declare class RateLimitTracker {
+    private info;
+    /**
+     * Updates rate limit info from response headers.
+     */
+    updateFromHeaders(headers: Headers): void;
+    /**
+     * Gets the current rate limit info.
+     */
+    getInfo(): RateLimitInfo | null;
+    /**
+     * Checks if we're running low on remaining requests.
+     * @param threshold Number of remaining requests to consider "low"
+     */
+    isLow(threshold?: number): boolean;
+    /**
+     * Checks if rate limit is exhausted.
+     */
+    isExhausted(): boolean;
+    /**
+     * Gets time until rate limit resets (in milliseconds).
+     * Returns 0 if reset time has passed or no info available.
+     */
+    getTimeUntilReset(): number;
+    /**
+     * Gets a human-readable status message.
+     */
+    getStatusMessage(): string;
+    /**
+     * Gets the reset time as a Date object.
+     * Returns undefined if no rate limit info is available.
+     */
+    getResetTime(): Date | undefined;
+}
+/**
+ * Default rate limit tracker instance for GitHub API.
+ */
+export declare const githubRateLimit: RateLimitTracker;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/utils/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/utils/rate-limit.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,IAAI,CAA8B;IAE1C;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAezC;;OAEG;IACH,OAAO,IAAI,aAAa,GAAG,IAAI;IAI/B;;;OAGG;IACH,KAAK,CAAC,SAAS,GAAE,MAAU,GAAG,OAAO;IAKrC;;OAEG;IACH,WAAW,IAAI,OAAO;IAKtB;;;OAGG;IACH,iBAAiB,IAAI,MAAM;IAO3B;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAkB1B;;;OAGG;IACH,YAAY,IAAI,IAAI,GAAG,SAAS;CAIjC;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,kBAAyB,CAAC"}

package/dist/utils/rate-limit.js

@@ -0,0 +1,89 @@
+/**
+ * Rate limit tracker for GitHub API.
+ */
+/**
+ * Tracks GitHub API rate limits.
+ */
+export class RateLimitTracker {
+    info = null;
+    /**
+     * Updates rate limit info from response headers.
+     */
+    updateFromHeaders(headers) {
+        const limit = headers.get("X-RateLimit-Limit");
+        const remaining = headers.get("X-RateLimit-Remaining");
+        const reset = headers.get("X-RateLimit-Reset");
+        if (limit && remaining && reset) {
+            this.info = {
+                limit: parseInt(limit, 10),
+                remaining: parseInt(remaining, 10),
+                reset: parseInt(reset, 10),
+                updatedAt: new Date(),
+            };
+        }
+    }
+    /**
+     * Gets the current rate limit info.
+     */
+    getInfo() {
+        return this.info;
+    }
+    /**
+     * Checks if we're running low on remaining requests.
+     * @param threshold Number of remaining requests to consider "low"
+     */
+    isLow(threshold = 5) {
+        if (!this.info)
+            return false;
+        return this.info.remaining < threshold;
+    }
+    /**
+     * Checks if rate limit is exhausted.
+     */
+    isExhausted() {
+        if (!this.info)
+            return false;
+        return this.info.remaining <= 0;
+    }
+    /**
+     * Gets time until rate limit resets (in milliseconds).
+     * Returns 0 if reset time has passed or no info available.
+     */
+    getTimeUntilReset() {
+        if (!this.info)
+            return 0;
+        const resetTime = this.info.reset * 1000; // Convert to ms
+        const now = Date.now();
+        return Math.max(0, resetTime - now);
+    }
+    /**
+     * Gets a human-readable status message.
+     */
+    getStatusMessage() {
+        if (!this.info) {
+            return "Rate limit info not available";
+        }
+        const minutesUntilReset = Math.ceil(this.getTimeUntilReset() / 60000);
+        if (this.isExhausted()) {
+            return `Rate limit exhausted. Resets in ${minutesUntilReset} minutes.`;
+        }
+        if (this.isLow()) {
+            return `Rate limit low: ${this.info.remaining}/${this.info.limit} remaining. Resets in ${minutesUntilReset} minutes.`;
+        }
+        return `Rate limit: ${this.info.remaining}/${this.info.limit} remaining`;
+    }
+    /**
+     * Gets the reset time as a Date object.
+     * Returns undefined if no rate limit info is available.
+     */
+    getResetTime() {
+        if (!this.info)
+            return undefined;
+        return new Date(this.info.reset * 1000);
+    }
+}
+/**
+ * Default rate limit tracker instance for GitHub API.
+ */
+export const githubRateLimit = new RateLimitTracker();
+//# sourceMappingURL=rate-limit.js.map