@mweinbach/apple-docs-mcp 1.0.0

package/dist/utils/user-agent-pool.d.ts

@@ -0,0 +1,241 @@
+/**
+ * User-Agent Pool Manager for rotating user agents to avoid detection
+ *
+ * Provides robust management of multiple User-Agent strings with:
+ * - Multiple rotation strategies (random, sequential, smart)
+ * - Automatic error handling and recovery
+ * - Performance statistics and monitoring
+ * - Thread-safe concurrent access
+ * - Browser type detection and header generation support
+ *
+ * @author Apple Docs MCP
+ * @version 1.0.0
+ */
+import type { UserAgent as UserAgentType, BrowserType } from '../types/headers.js';
+/**
+ * Configuration options for the User-Agent pool
+ */
+export interface UserAgentPoolConfig {
+    /** Rotation strategy to use */
+    strategy?: RotationStrategy;
+    /** How long to disable failed User-Agents (in milliseconds) */
+    disableDuration?: number;
+    /** Maximum number of failures before disabling a User-Agent */
+    failureThreshold?: number;
+    /** Minimum success rate to keep a User-Agent enabled (0-1) */
+    minSuccessRate?: number;
+}
+/**
+ * Rotation strategies available
+ */
+export type RotationStrategy = 'random' | 'sequential' | 'smart';
+/**
+ * Statistics for a single User-Agent
+ */
+export interface AgentStats {
+    value: string;
+    successCount: number;
+    failureCount: number;
+    successRate: number;
+    totalRequests: number;
+    isEnabled: boolean;
+    lastUsed?: Date;
+    consecutiveFailures: number;
+}
+/**
+ * Overall pool statistics
+ */
+export interface PoolStats {
+    /** Total number of User-Agents in pool */
+    total: number;
+    /** Number of currently enabled User-Agents */
+    enabled: number;
+    /** Number of currently disabled User-Agents */
+    disabled: number;
+    /** Total requests made across all User-Agents */
+    totalRequests: number;
+    /** Overall success rate (0-100) */
+    successRate: number;
+    /** Current rotation strategy */
+    strategy: RotationStrategy;
+    /** Pool health score (0-100) */
+    healthScore: number;
+}
+/**
+ * User-Agent Pool Manager
+ *
+ * Manages a pool of User-Agent strings with rotation, error handling,
+ * and automatic recovery capabilities.
+ *
+ * @example
+ * ```typescript
+ * const pool = new UserAgentPool([
+ *   'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36',
+ *   'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36'
+ * ]);
+ *
+ * const userAgent = pool.getNext();
+ * // ... make request ...
+ * if (response.ok) {
+ *   pool.markSuccess(userAgent);
+ * } else {
+ *   pool.markFailure(userAgent, response.status);
+ * }
+ * ```
+ */
+export declare class UserAgentPool {
+    private agents;
+    private currentIndex;
+    private config;
+    private mutex;
+    /**
+     * Create a new User-Agent pool
+     *
+     * @param agents - Array of User-Agent strings to manage
+     * @param config - Configuration options
+     * @throws {Error} When agents array is empty or contains invalid values
+     */
+    constructor(agents: string[], config?: UserAgentPoolConfig);
+    /**
+     * Get the next User-Agent string using the configured strategy
+     *
+     * This method is thread-safe and handles automatic recovery of disabled agents.
+     *
+     * @returns The next User-Agent string to use
+     * @throws {Error} When no User-Agents are available
+     */
+    getNext(): Promise<string>;
+    /**
+     * Mark a User-Agent as having failed a request
+     *
+     * @param userAgent - The User-Agent string that failed
+     * @param statusCode - HTTP status code of the failure (optional)
+     */
+    markFailure(userAgent: string, statusCode?: number): Promise<void>;
+    /**
+     * Mark a User-Agent as having succeeded a request
+     *
+     * @param userAgent - The User-Agent string that succeeded
+     */
+    markSuccess(userAgent: string): Promise<void>;
+    /**
+     * Add a new User-Agent to the pool
+     *
+     * @param userAgent - The User-Agent string to add
+     * @throws {Error} When User-Agent is invalid or already exists
+     */
+    addAgent(userAgent: string): Promise<void>;
+    /**
+     * Remove a User-Agent from the pool
+     *
+     * @param userAgent - The User-Agent string to remove
+     * @throws {Error} When trying to remove the last User-Agent
+     */
+    removeAgent(userAgent: string): Promise<void>;
+    /**
+     * Get statistics for all User-Agents in the pool
+     *
+     * @returns Array of statistics for each User-Agent
+     */
+    getAgentStats(): AgentStats[];
+    /**
+     * Get overall pool statistics
+     *
+     * @returns Pool-wide statistics
+     */
+    getStats(): PoolStats;
+    /**
+     * Reset all statistics while keeping the User-Agents
+     */
+    resetStats(): Promise<void>;
+    /**
+     * Get the current configuration
+     *
+     * @returns Current pool configuration
+     */
+    getConfig(): Readonly<Required<UserAgentPoolConfig>>;
+    /**
+     * Get the next User-Agent as a structured UserAgent object
+     *
+     * This method provides enhanced information about the User-Agent including
+     * browser type, version, OS details, and architecture information.
+     *
+     * @returns Promise resolving to a UserAgent object with parsed information
+     * @throws {Error} When no User-Agents are available
+     */
+    getNextUserAgent(): Promise<UserAgentType>;
+    /**
+     * Get a random User-Agent string filtered by browser type
+     *
+     * @param browserType - Desired browser type
+     * @returns Promise resolving to a User-Agent string of the specified type
+     * @throws {Error} When no User-Agents of the specified type are available
+     */
+    getByBrowserType(browserType: BrowserType): Promise<string>;
+    /**
+     * Get a random User-Agent object filtered by browser type
+     *
+     * @param browserType - Desired browser type
+     * @returns Promise resolving to a UserAgent object of the specified type
+     * @throws {Error} When no User-Agents of the specified type are available
+     */
+    getUserAgentByBrowserType(browserType: BrowserType): Promise<UserAgentType>;
+    /**
+     * Get statistics grouped by browser type
+     *
+     * @returns Statistics organized by browser type
+     */
+    getStatsByBrowserType(): Record<BrowserType, {
+        count: number;
+        enabled: number;
+        successRate: number;
+    }>;
+    /**
+     * Get all available browser types in the pool
+     *
+     * @returns Array of browser types present in the pool
+     */
+    getAvailableBrowserTypes(): BrowserType[];
+    private selectByStrategy;
+    private selectRandom;
+    private selectSequential;
+    private selectSmart;
+    private selectAndUseAgent;
+    private findAgent;
+    private shouldDisableAgent;
+    private getAgentSuccessRate;
+    private recoverDisabledAgents;
+    private selectFallbackAgent;
+    private calculateHealthScore;
+    private removeDuplicates;
+    private shuffleAgents;
+}
+/**
+ * Pre-defined User-Agent strings for common browsers
+ * Covers Chrome, Firefox, Safari, and Edge across different platforms
+ */
+export declare const COMMON_USER_AGENTS: {
+    readonly CHROME_MAC_INTEL: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36";
+    readonly CHROME_MAC_APPLE: "Mozilla/5.0 (Macintosh; arm64 Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36";
+    readonly CHROME_WINDOWS: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36";
+    readonly CHROME_LINUX: "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36";
+    readonly FIREFOX_MAC_INTEL: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:122.0) Gecko/20100101 Firefox/122.0";
+    readonly FIREFOX_MAC_APPLE: "Mozilla/5.0 (Macintosh; arm64 Mac OS X 10.15; rv:122.0) Gecko/20100101 Firefox/122.0";
+    readonly FIREFOX_WINDOWS: "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:122.0) Gecko/20100101 Firefox/122.0";
+    readonly FIREFOX_LINUX: "Mozilla/5.0 (X11; Linux x86_64; rv:122.0) Gecko/20100101 Firefox/122.0";
+    readonly SAFARI_MAC_INTEL_15_1: "Mozilla/5.0 (Macintosh; Intel Mac OS X 15_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.1 Safari/605.1.15";
+    readonly SAFARI_MAC_APPLE_15_1: "Mozilla/5.0 (Macintosh; arm64 Mac OS X 15_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.1 Safari/605.1.15";
+    readonly SAFARI_MAC_INTEL_14_7: "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.6.1 Safari/605.1.15";
+    readonly SAFARI_MAC_APPLE_14_7: "Mozilla/5.0 (Macintosh; arm64 Mac OS X 14_7_1) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.6.1 Safari/605.1.15";
+    readonly EDGE_WINDOWS: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36 Edg/121.0.0.0";
+    readonly EDGE_MAC_INTEL: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36 Edg/121.0.0.0";
+    readonly EDGE_MAC_APPLE: "Mozilla/5.0 (Macintosh; arm64 Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36 Edg/121.0.0.0";
+};
+/**
+ * Create a default User-Agent pool with common browser agents
+ *
+ * @param config - Configuration options for the pool
+ * @returns A new UserAgentPool instance with common User-Agents
+ */
+export declare function createDefaultPool(config?: UserAgentPoolConfig): UserAgentPool;
+//# sourceMappingURL=user-agent-pool.d.ts.map

package/dist/utils/user-agent-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-agent-pool.d.ts","sourceRoot":"","sources":["../../src/utils/user-agent-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,IAAI,aAAa,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGnF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC;AAsBjE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;CACrB;AAYD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,KAAK,CAAoB;IAEjC;;;;;;OAMG;gBACS,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,GAAE,mBAAwB;IAsC9D;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,MAAM,CAAC;IA0BhC;;;;;OAKG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBxE;;;;OAIG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBnD;;;;;OAKG;IACG,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBhD;;;;;OAKG;IACG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBnD;;;;OAIG;IACH,aAAa,IAAI,UAAU,EAAE;IAa7B;;;;OAIG;IACH,QAAQ,IAAI,SAAS;IAqBrB;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAajC;;;;OAIG;IACH,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;IAIpD;;;;;;;;OAQG;IACG,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC;IAKhD;;;;;;OAMG;IACG,gBAAgB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBjE;;;;;;OAMG;IACG,yBAAyB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAKjF;;;;OAIG;IACH,qBAAqB,IAAI,MAAM,CAAC,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAsCrG;;;;OAIG;IACH,wBAAwB,IAAI,WAAW,EAAE;IAazC,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,gBAAgB;IAexB,OAAO,CAAC,WAAW;IA6BnB,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,kBAAkB;IAuB1B,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,mBAAmB;IAgC3B,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,aAAa;CAMtB;AAiBD;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;CAuBrB,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,GAAE,mBAAwB,GAAG,aAAa,CAEjF"}