novada-proxy-core 0.0.1

package/build/adapters/brightdata.d.ts

@@ -0,0 +1,24 @@
+import type { ProxyAdapter } from "./types.js";
+/**
+ * BrightData residential proxy adapter.
+ *
+ * BrightData (formerly Luminati) is the largest residential proxy network.
+ * This adapter encodes country, city, and session targeting automatically
+ * using BrightData's username-suffix format.
+ *
+ * Auth format:
+ *   BASE_USERNAME[-country-XX][-city-CITY][-session-ID]:PASS@HOST:PORT
+ *
+ * Where BASE_USERNAME is your full BrightData username including zone:
+ *   e.g. brd-customer-abc123-zone-residential
+ *
+ * Get credentials:
+ *   brightdata.com → Proxies & Scraping → Residential → Access Parameters
+ *
+ * Env vars:
+ *   BRIGHTDATA_USER  — required (full username, e.g. brd-customer-abc123-zone-residential)
+ *   BRIGHTDATA_PASS  — required
+ *   BRIGHTDATA_HOST  — optional (default: zproxy.lum-superproxy.io)
+ *   BRIGHTDATA_PORT  — optional (default: 22225)
+ */
+export declare const BrightDataAdapter: ProxyAdapter;

package/build/adapters/brightdata.js

@@ -0,0 +1,56 @@
+/**
+ * BrightData residential proxy adapter.
+ *
+ * BrightData (formerly Luminati) is the largest residential proxy network.
+ * This adapter encodes country, city, and session targeting automatically
+ * using BrightData's username-suffix format.
+ *
+ * Auth format:
+ *   BASE_USERNAME[-country-XX][-city-CITY][-session-ID]:PASS@HOST:PORT
+ *
+ * Where BASE_USERNAME is your full BrightData username including zone:
+ *   e.g. brd-customer-abc123-zone-residential
+ *
+ * Get credentials:
+ *   brightdata.com → Proxies & Scraping → Residential → Access Parameters
+ *
+ * Env vars:
+ *   BRIGHTDATA_USER  — required (full username, e.g. brd-customer-abc123-zone-residential)
+ *   BRIGHTDATA_PASS  — required
+ *   BRIGHTDATA_HOST  — optional (default: zproxy.lum-superproxy.io)
+ *   BRIGHTDATA_PORT  — optional (default: 22225)
+ */
+export const BrightDataAdapter = {
+    name: "brightdata",
+    displayName: "BrightData",
+    lastVerified: "2026-04-09",
+    capabilities: { country: true, city: true, sticky: true },
+    credentialDocs: "brightdata.com → Proxies & Scraping → Residential → Access Parameters",
+    sensitiveFields: ["pass"],
+    loadCredentials(env) {
+        const user = env.BRIGHTDATA_USER;
+        const pass = env.BRIGHTDATA_PASS;
+        if (!user || !pass)
+            return null;
+        const rawPort = Number(env.BRIGHTDATA_PORT);
+        const port = Number.isInteger(rawPort) && rawPort > 0 && rawPort < 65536
+            ? rawPort : 22225;
+        return {
+            user,
+            pass,
+            host: env.BRIGHTDATA_HOST || "zproxy.lum-superproxy.io",
+            port: String(port),
+        };
+    },
+    buildProxyUrl(credentials, params) {
+        // BrightData appends targeting params to the username with `-` delimiter
+        let username = credentials.user;
+        if (params.country)
+            username += `-country-${params.country.toLowerCase()}`;
+        if (params.city)
+            username += `-city-${params.city.toLowerCase()}`;
+        if (params.session_id)
+            username += `-sid-${params.session_id}`;
+        return `http://${encodeURIComponent(username)}:${encodeURIComponent(credentials.pass)}@${credentials.host}:${credentials.port}`;
+    },
+};

package/build/adapters/generic.d.ts

@@ -0,0 +1,32 @@
+import type { ProxyAdapter } from "./types.js";
+/**
+ * Generic HTTP Proxy adapter.
+ *
+ * Set PROXY_URL=http://user:pass@host:port to use any standard HTTP proxy.
+ *
+ * Compatible with (among others):
+ *   BrightData  — https://brightdata.com  (zproxy.lum-superproxy.io:22225)
+ *   Smartproxy  — https://smartproxy.com  (gate.smartproxy.com:10001)
+ *   Oxylabs     — https://oxylabs.io      (pr.oxylabs.io:7777)
+ *   IPRoyal     — https://iproyal.com     (geo.iproyal.com:12321)
+ *   Any HTTP CONNECT-capable proxy
+ *
+ * ⚠️  Country, city, and session_id targeting parameters are NOT automatically
+ *     applied — encode them directly in PROXY_URL per your provider's format.
+ *     For full targeting support with automatic parameter encoding, use a
+ *     provider-specific adapter (e.g. Novada via NOVADA_PROXY_USER/PASS).
+ *
+ * Examples:
+ *   # BrightData with US targeting (encoded in username)
+ *   PROXY_URL=http://user-country-us:pass@zproxy.lum-superproxy.io:22225
+ *
+ *   # Smartproxy with DE targeting
+ *   PROXY_URL=http://user-country-DE:pass@gate.smartproxy.com:10001
+ *
+ *   # Plain proxy (rotating, no targeting)
+ *   PROXY_URL=http://user:pass@proxy.example.com:8080
+ *
+ * Env vars:
+ *   PROXY_URL — required. Must start with http:// or https://
+ */
+export declare const GenericHttpAdapter: ProxyAdapter;

package/build/adapters/generic.js

@@ -0,0 +1,63 @@
+/**
+ * Generic HTTP Proxy adapter.
+ *
+ * Set PROXY_URL=http://user:pass@host:port to use any standard HTTP proxy.
+ *
+ * Compatible with (among others):
+ *   BrightData  — https://brightdata.com  (zproxy.lum-superproxy.io:22225)
+ *   Smartproxy  — https://smartproxy.com  (gate.smartproxy.com:10001)
+ *   Oxylabs     — https://oxylabs.io      (pr.oxylabs.io:7777)
+ *   IPRoyal     — https://iproyal.com     (geo.iproyal.com:12321)
+ *   Any HTTP CONNECT-capable proxy
+ *
+ * ⚠️  Country, city, and session_id targeting parameters are NOT automatically
+ *     applied — encode them directly in PROXY_URL per your provider's format.
+ *     For full targeting support with automatic parameter encoding, use a
+ *     provider-specific adapter (e.g. Novada via NOVADA_PROXY_USER/PASS).
+ *
+ * Examples:
+ *   # BrightData with US targeting (encoded in username)
+ *   PROXY_URL=http://user-country-us:pass@zproxy.lum-superproxy.io:22225
+ *
+ *   # Smartproxy with DE targeting
+ *   PROXY_URL=http://user-country-DE:pass@gate.smartproxy.com:10001
+ *
+ *   # Plain proxy (rotating, no targeting)
+ *   PROXY_URL=http://user:pass@proxy.example.com:8080
+ *
+ * Env vars:
+ *   PROXY_URL — required. Must start with http:// or https://
+ */
+export const GenericHttpAdapter = {
+    name: "generic",
+    displayName: "Generic HTTP Proxy",
+    lastVerified: "2026-04-09",
+    capabilities: { country: false, city: false, sticky: false },
+    credentialDocs: "Set PROXY_URL=http://user:pass@host:port",
+    sensitiveFields: ["pass", "proxyUrl"],
+    loadCredentials(env) {
+        const raw = env.PROXY_URL;
+        if (!raw)
+            return null;
+        let parsed;
+        try {
+            parsed = new URL(raw);
+        }
+        catch {
+            // Malformed URL — do not throw, just decline so the error surfaces cleanly
+            return null;
+        }
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+            return null;
+        return {
+            proxyUrl: raw,
+            user: parsed.username || "",
+            pass: parsed.password || "",
+        };
+    },
+    buildProxyUrl(credentials, _params) {
+        // Return the URL as-is. Country/city/session_id must be encoded
+        // in the URL by the user per their provider's specific format.
+        return credentials.proxyUrl;
+    },
+};

package/build/adapters/index.d.ts

@@ -0,0 +1,16 @@
+import type { ProxyAdapter, ProxyCredentials } from "./types.js";
+export type { ProxyAdapter, ProxyCredentials, ProxyRequestParams, AdapterCapabilities } from "./types.js";
+export interface ResolvedAdapter {
+    adapter: ProxyAdapter;
+    credentials: ProxyCredentials;
+}
+/**
+ * Resolve which proxy adapter to use based on available environment variables.
+ * Returns the first configured adapter (Novada wins if multiple are set).
+ * Returns null if no proxy provider is configured.
+ */
+export declare function resolveAdapter(env: NodeJS.ProcessEnv): ResolvedAdapter | null;
+/**
+ * List all registered adapters (for --help and status output).
+ */
+export declare function listAdapters(): ProxyAdapter[];

package/build/adapters/index.js

@@ -0,0 +1,42 @@
+import { NovadaAdapter } from "./novada.js";
+import { GenericHttpAdapter } from "./generic.js";
+import { BrightDataAdapter } from "./brightdata.js";
+import { SmartproxyAdapter } from "./smartproxy.js";
+import { OxylabsAdapter } from "./oxylabs.js";
+/**
+ * Registered proxy adapters in priority order.
+ *
+ * Resolution: the first adapter whose loadCredentials() returns non-null wins.
+ * Novada is always first — it's our default and priority provider.
+ *
+ * To add a provider:
+ *   1. Create src/adapters/<provider>.ts implementing ProxyAdapter
+ *   2. Import it here and add it to the array below
+ *   3. Nothing else changes
+ */
+const ADAPTERS = [
+    NovadaAdapter, // Always first — default, deepest integration
+    BrightDataAdapter, // BRIGHTDATA_USER + BRIGHTDATA_PASS
+    SmartproxyAdapter, // SMARTPROXY_USER + SMARTPROXY_PASS
+    OxylabsAdapter, // OXYLABS_USER + OXYLABS_PASS
+    GenericHttpAdapter, // Always last — PROXY_URL fallback (no auto-targeting)
+];
+/**
+ * Resolve which proxy adapter to use based on available environment variables.
+ * Returns the first configured adapter (Novada wins if multiple are set).
+ * Returns null if no proxy provider is configured.
+ */
+export function resolveAdapter(env) {
+    for (const adapter of ADAPTERS) {
+        const credentials = adapter.loadCredentials(env);
+        if (credentials)
+            return { adapter, credentials };
+    }
+    return null;
+}
+/**
+ * List all registered adapters (for --help and status output).
+ */
+export function listAdapters() {
+    return [...ADAPTERS];
+}

package/build/adapters/novada.d.ts

@@ -0,0 +1,23 @@
+import type { ProxyAdapter } from "./types.js";
+/**
+ * Novada residential proxy adapter.
+ *
+ * Auth format: USERNAME-zone-ZONE[-region-XX][-city-CITY][-session-ID-sessTime-N]:PASS@HOST:PORT
+ *
+ * Rules enforced here (not in tool validators — they handle user-facing input):
+ * - Hyphen `-` is Novada's segment delimiter → never appears in country/city/session_id
+ *   (enforced upstream in validateFetchParams / validateSessionParams)
+ * - session_id → `-session-ID-sessTime-N` suffix (sessTime required for sticky IP)
+ * - country → `-region-XX` suffix (lowercased)
+ * - city    → `-city-CITY` suffix (lowercased)
+ *
+ * Env vars:
+ *   NOVADA_PROXY_USER  — required
+ *   NOVADA_PROXY_PASS  — required
+ *   NOVADA_PROXY_HOST  — optional; defaults to super.novada.pro (shared load balancer)
+ *                        Set to your account-specific host for reliable sticky sessions.
+ *   NOVADA_PROXY_PORT  — optional; defaults to 7777
+ *   NOVADA_PROXY_ZONE  — optional; defaults to "res" (residential).
+ *                        Other zones: "isp" (rotating ISP), "dcp" (rotating datacenter)
+ */
+export declare const NovadaAdapter: ProxyAdapter;

package/build/adapters/novada.js

@@ -0,0 +1,61 @@
+/**
+ * Novada residential proxy adapter.
+ *
+ * Auth format: USERNAME-zone-ZONE[-region-XX][-city-CITY][-session-ID-sessTime-N]:PASS@HOST:PORT
+ *
+ * Rules enforced here (not in tool validators — they handle user-facing input):
+ * - Hyphen `-` is Novada's segment delimiter → never appears in country/city/session_id
+ *   (enforced upstream in validateFetchParams / validateSessionParams)
+ * - session_id → `-session-ID-sessTime-N` suffix (sessTime required for sticky IP)
+ * - country → `-region-XX` suffix (lowercased)
+ * - city    → `-city-CITY` suffix (lowercased)
+ *
+ * Env vars:
+ *   NOVADA_PROXY_USER  — required
+ *   NOVADA_PROXY_PASS  — required
+ *   NOVADA_PROXY_HOST  — optional; defaults to super.novada.pro (shared load balancer)
+ *                        Set to your account-specific host for reliable sticky sessions.
+ *   NOVADA_PROXY_PORT  — optional; defaults to 7777
+ *   NOVADA_PROXY_ZONE  — optional; defaults to "res" (residential).
+ *                        Other zones: "isp" (rotating ISP), "dcp" (rotating datacenter)
+ */
+export const NovadaAdapter = {
+    name: "novada",
+    displayName: "Novada",
+    lastVerified: "2026-04-09",
+    capabilities: { country: true, city: true, sticky: true },
+    credentialDocs: "novada.com → Dashboard → Residential Proxies → Endpoint Generator",
+    sensitiveFields: ["pass"],
+    loadCredentials(env) {
+        const user = env.NOVADA_PROXY_USER;
+        const pass = env.NOVADA_PROXY_PASS;
+        if (!user || !pass)
+            return null;
+        const rawPort = Number(env.NOVADA_PROXY_PORT);
+        const port = Number.isInteger(rawPort) && rawPort > 0 && rawPort < 65536
+            ? rawPort : 7777;
+        const zone = env.NOVADA_PROXY_ZONE || "res";
+        return {
+            user,
+            pass,
+            host: env.NOVADA_PROXY_HOST || "super.novada.pro",
+            port: String(port),
+            zone,
+        };
+    },
+    buildProxyUrl(credentials, params) {
+        const zone = credentials.zone || "res";
+        let username = `${credentials.user}-zone-${zone}`;
+        if (params.country)
+            username += `-region-${params.country.toLowerCase()}`;
+        if (params.city)
+            username += `-city-${params.city.toLowerCase()}`;
+        if (params.session_id) {
+            // sessTime is required for sticky IP on all Novada zones.
+            // Default: 5 min for res/dcp, 120 min for isp. Max: 120 min res, 360 min isp, 30 min dcp.
+            const defaultSessTime = zone === "isp" ? 120 : 5;
+            username += `-session-${params.session_id}-sessTime-${defaultSessTime}`;
+        }
+        return `http://${encodeURIComponent(username)}:${encodeURIComponent(credentials.pass)}@${credentials.host}:${credentials.port}`;
+    },
+};

package/build/adapters/oxylabs.d.ts

@@ -0,0 +1,22 @@
+import type { ProxyAdapter } from "./types.js";
+/**
+ * Oxylabs residential proxy adapter.
+ *
+ * Oxylabs uses a different format: country and city are encoded as
+ * `-cc-XX` and `-city-CITY` suffixes. Session stickiness uses `-sessid-ID`.
+ *
+ * Auth format:
+ *   USER[-cc-XX][-city-CITY][-sessid-ID]:PASS@pr.oxylabs.io:PORT
+ *
+ * Default port: 7777.
+ *
+ * Get credentials:
+ *   oxylabs.io → Dashboard → Residential Proxies → Access Details
+ *
+ * Env vars:
+ *   OXYLABS_USER  — required
+ *   OXYLABS_PASS  — required
+ *   OXYLABS_HOST  — optional (default: pr.oxylabs.io)
+ *   OXYLABS_PORT  — optional (default: 7777)
+ */
+export declare const OxylabsAdapter: ProxyAdapter;

package/build/adapters/oxylabs.js

@@ -0,0 +1,54 @@
+/**
+ * Oxylabs residential proxy adapter.
+ *
+ * Oxylabs uses a different format: country and city are encoded as
+ * `-cc-XX` and `-city-CITY` suffixes. Session stickiness uses `-sessid-ID`.
+ *
+ * Auth format:
+ *   USER[-cc-XX][-city-CITY][-sessid-ID]:PASS@pr.oxylabs.io:PORT
+ *
+ * Default port: 7777.
+ *
+ * Get credentials:
+ *   oxylabs.io → Dashboard → Residential Proxies → Access Details
+ *
+ * Env vars:
+ *   OXYLABS_USER  — required
+ *   OXYLABS_PASS  — required
+ *   OXYLABS_HOST  — optional (default: pr.oxylabs.io)
+ *   OXYLABS_PORT  — optional (default: 7777)
+ */
+export const OxylabsAdapter = {
+    name: "oxylabs",
+    displayName: "Oxylabs",
+    lastVerified: "2026-04-09",
+    capabilities: { country: true, city: true, sticky: true },
+    credentialDocs: "oxylabs.io → Dashboard → Residential Proxies → Access Details",
+    sensitiveFields: ["pass"],
+    loadCredentials(env) {
+        const user = env.OXYLABS_USER;
+        const pass = env.OXYLABS_PASS;
+        if (!user || !pass)
+            return null;
+        const rawPort = Number(env.OXYLABS_PORT);
+        const port = Number.isInteger(rawPort) && rawPort > 0 && rawPort < 65536
+            ? rawPort : 7777;
+        return {
+            user,
+            pass,
+            host: env.OXYLABS_HOST || "pr.oxylabs.io",
+            port: String(port),
+        };
+    },
+    buildProxyUrl(credentials, params) {
+        // Oxylabs uses -cc-XX for country, -city-CITY for city, -sessid-ID for sticky
+        let username = credentials.user;
+        if (params.country)
+            username += `-cc-${params.country.toUpperCase()}`;
+        if (params.city)
+            username += `-city-${params.city.toLowerCase()}`;
+        if (params.session_id)
+            username += `-sessid-${params.session_id}`;
+        return `http://${encodeURIComponent(username)}:${encodeURIComponent(credentials.pass)}@${credentials.host}:${credentials.port}`;
+    },
+};

package/build/adapters/smartproxy.d.ts

@@ -0,0 +1,22 @@
+import type { ProxyAdapter } from "./types.js";
+/**
+ * Smartproxy residential proxy adapter.
+ *
+ * Smartproxy uses a username-suffix format similar to BrightData but with
+ * different segment names. Country is encoded as `-country-XX` (uppercase).
+ *
+ * Auth format:
+ *   USER[-country-XX][-city-CITY][-session-SESSIONID]:PASS@gate.smartproxy.com:PORT
+ *
+ * Default port: 10001 (rotating). Use 10000 for US-only pool.
+ *
+ * Get credentials:
+ *   smartproxy.com → Dashboard → Residential → Endpoint Generator
+ *
+ * Env vars:
+ *   SMARTPROXY_USER  — required
+ *   SMARTPROXY_PASS  — required
+ *   SMARTPROXY_HOST  — optional (default: gate.smartproxy.com)
+ *   SMARTPROXY_PORT  — optional (default: 10001)
+ */
+export declare const SmartproxyAdapter: ProxyAdapter;

package/build/adapters/smartproxy.js

@@ -0,0 +1,54 @@
+/**
+ * Smartproxy residential proxy adapter.
+ *
+ * Smartproxy uses a username-suffix format similar to BrightData but with
+ * different segment names. Country is encoded as `-country-XX` (uppercase).
+ *
+ * Auth format:
+ *   USER[-country-XX][-city-CITY][-session-SESSIONID]:PASS@gate.smartproxy.com:PORT
+ *
+ * Default port: 10001 (rotating). Use 10000 for US-only pool.
+ *
+ * Get credentials:
+ *   smartproxy.com → Dashboard → Residential → Endpoint Generator
+ *
+ * Env vars:
+ *   SMARTPROXY_USER  — required
+ *   SMARTPROXY_PASS  — required
+ *   SMARTPROXY_HOST  — optional (default: gate.smartproxy.com)
+ *   SMARTPROXY_PORT  — optional (default: 10001)
+ */
+export const SmartproxyAdapter = {
+    name: "smartproxy",
+    displayName: "Smartproxy",
+    lastVerified: "2026-04-09",
+    capabilities: { country: true, city: true, sticky: true },
+    credentialDocs: "smartproxy.com → Dashboard → Residential → Endpoint Generator",
+    sensitiveFields: ["pass"],
+    loadCredentials(env) {
+        const user = env.SMARTPROXY_USER;
+        const pass = env.SMARTPROXY_PASS;
+        if (!user || !pass)
+            return null;
+        const rawPort = Number(env.SMARTPROXY_PORT);
+        const port = Number.isInteger(rawPort) && rawPort > 0 && rawPort < 65536
+            ? rawPort : 10001;
+        return {
+            user,
+            pass,
+            host: env.SMARTPROXY_HOST || "gate.smartproxy.com",
+            port: String(port),
+        };
+    },
+    buildProxyUrl(credentials, params) {
+        // Smartproxy appends targeting params to the username with `-` delimiter
+        let username = credentials.user;
+        if (params.country)
+            username += `-country-${params.country.toUpperCase()}`;
+        if (params.city)
+            username += `-city-${params.city.toLowerCase()}`;
+        if (params.session_id)
+            username += `-session-${params.session_id}`;
+        return `http://${encodeURIComponent(username)}:${encodeURIComponent(credentials.pass)}@${credentials.host}:${credentials.port}`;
+    },
+};

package/build/adapters/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ProxyAdapter — the contract every proxy provider must satisfy.
+ *
+ * Adding a new provider = implement this interface in a new file,
+ * register it in index.ts. Nothing else changes.
+ */
+export interface ProxyCredentials {
+    /** Provider-specific key/value pairs (e.g. user, pass, host, port). */
+    [key: string]: string;
+}
+export interface AdapterCapabilities {
+    /** Supports 2-letter country-level geo-targeting. */
+    country: boolean;
+    /** Supports city-level geo-targeting. */
+    city: boolean;
+    /** Supports sticky sessions (same IP across requests with same session_id). */
+    sticky: boolean;
+}
+export interface ProxyRequestParams {
+    country?: string;
+    city?: string;
+    session_id?: string;
+}
+export interface ProxyAdapter {
+    /** Internal identifier. Snake-case, lowercase. e.g. "novada", "brightdata" */
+    readonly name: string;
+    /** Human-readable name shown in error messages and status output. */
+    readonly displayName: string;
+    /**
+     * ISO date when this adapter was last tested against live credentials.
+     * Shown to users so they know how fresh the integration is.
+     */
+    readonly lastVerified: string;
+    /** Which targeting features this provider supports. */
+    readonly capabilities: AdapterCapabilities;
+    /** URL or description of where users get credentials for this provider. */
+    readonly credentialDocs: string;
+    /**
+     * Keys in ProxyCredentials that contain secrets.
+     * Used to redact sensitive values from error messages before surfacing to agents.
+     */
+    readonly sensitiveFields: ReadonlyArray<string>;
+    /**
+     * Reads environment variables and returns a credentials object,
+     * or null if this provider is not configured (required env vars missing).
+     *
+     * Implementations should not throw — return null for missing/incomplete config.
+     */
+    loadCredentials(env: NodeJS.ProcessEnv): ProxyCredentials | null;
+    /**
+     * Builds the full HTTP proxy URL for a given request.
+     * Called once per request (or per retry batch).
+     *
+     * Must return a URL in the form:
+     *   http://[encoded-user]:[encoded-pass]@[host]:[port]
+     */
+    buildProxyUrl(credentials: ProxyCredentials, params: ProxyRequestParams): string;
+}

package/build/adapters/types.js

@@ -0,0 +1,7 @@
+/**
+ * ProxyAdapter — the contract every proxy provider must satisfy.
+ *
+ * Adding a new provider = implement this interface in a new file,
+ * register it in index.ts. Nothing else changes.
+ */
+export {};

package/build/config.d.ts

@@ -0,0 +1,4 @@
+export declare const VERSION = "1.8.2";
+export declare const NPM_PACKAGE = "novada-proxy-mcp";
+export declare const NOVADA_SEARCH_URL = "https://scraperapi.novada.com/search";
+export declare const DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";

package/build/config.js

@@ -0,0 +1,7 @@
+export const VERSION = "1.8.2";
+// npm package name — used in CLI help and error messages
+export const NPM_PACKAGE = "novada-proxy-mcp";
+// Novada Scraper API — web search
+export const NOVADA_SEARCH_URL = "https://scraperapi.novada.com/search";
+// Default User-Agent for all HTTP requests through the proxy
+export const DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";

package/build/errors.d.ts

@@ -0,0 +1,2 @@
+import type { ProxyErrorResponse } from "./types.js";
+export declare function classifyError(err: unknown): ProxyErrorResponse;

package/build/errors.js

@@ -0,0 +1,58 @@
+import axios from "axios";
+export function classifyError(err) {
+    const ax = axios.isAxiosError(err);
+    const status = ax ? err.response?.status : undefined;
+    const msg = err instanceof Error ? err.message : String(err);
+    if (ax && status === 429)
+        return { ok: false, error: {
+                code: "RATE_LIMITED", message: "HTTP 429 — rate limited",
+                recoverable: true,
+                agent_instruction: "Wait 5 seconds and retry. Consider reducing request frequency.",
+                retry_after_seconds: 5
+            } };
+    if (ax && status && status >= 400 && status < 500)
+        return { ok: false, error: {
+                code: "BOT_DETECTION_SUSPECTED",
+                message: `HTTP ${status} — request blocked by target`,
+                recoverable: true,
+                agent_instruction: "Try novada_proxy_render (real browser). Or retry with a different country/session_id. If render also returns 4xx, the page may genuinely not exist — stop retrying."
+            } };
+    if (msg.includes("timeout") || msg.includes("ECONNABORTED"))
+        return { ok: false, error: {
+                code: "TIMEOUT", message: "Request timed out",
+                recoverable: true,
+                agent_instruction: "Increase the timeout parameter or retry. For JS-heavy pages, use novada_proxy_render.",
+                retry_after_seconds: 2
+            } };
+    if (msg.includes("ENOTFOUND") || msg.includes("EAI_AGAIN") || msg.includes("getaddrinfo"))
+        return { ok: false, error: {
+                code: "NETWORK_ERROR", message: "DNS resolution failed — hostname not found",
+                recoverable: false,
+                agent_instruction: "The hostname could not be resolved. Verify the URL is correct and the domain exists.",
+            } };
+    if (msg.includes("TLS") || msg.includes("SSL") || msg.includes("socket disconnect") || msg.includes("secure TLS") || msg.includes("certificate") || msg.includes("issuer cert"))
+        return { ok: false, error: {
+                code: "TLS_ERROR", message: "TLS/SSL connection failed",
+                recoverable: true,
+                agent_instruction: "The target rejected the proxy connection. Retry with a different country parameter or use novada_proxy_render. If this is an unrecognized domain, verify it exists — proxy-side DNS failures may appear as TLS errors.",
+                retry_after_seconds: 2
+            } };
+    if (msg.includes("No proxy provider") || msg.includes("not configured"))
+        return { ok: false, error: {
+                code: "PROVIDER_NOT_CONFIGURED", message: msg,
+                recoverable: false,
+                agent_instruction: "Set NOVADA_PROXY_USER and NOVADA_PROXY_PASS env vars and restart the MCP server."
+            } };
+    const INPUT_ERROR_PHRASES = ["is required", "must be", "must start with", "must contain", "letters, numbers", "max 64", "max 50", "between 1 and"];
+    if (INPUT_ERROR_PHRASES.some(p => msg.includes(p)))
+        return { ok: false, error: {
+                code: "INVALID_INPUT", message: msg,
+                recoverable: false,
+                agent_instruction: "Fix the input parameters and retry. Check the tool's inputSchema for valid values."
+            } };
+    return { ok: false, error: {
+            code: "UNKNOWN_ERROR", message: msg,
+            recoverable: true,
+            agent_instruction: "Retry the request. Check novada_proxy_status for network health."
+        } };
+}

package/build/index.d.ts

@@ -0,0 +1,28 @@
+export type { ProxyErrorCode, QuotaMeta, ProxySuccessResponse, ProxyErrorResponse, ProxyResponse, } from "./types.js";
+export { VERSION, NPM_PACKAGE } from "./config.js";
+export { classifyError } from "./errors.js";
+export type { ProxyAdapter, ProxyCredentials, ProxyRequestParams, AdapterCapabilities, } from "./adapters/index.js";
+export { resolveAdapter, listAdapters } from "./adapters/index.js";
+export type { ResolvedAdapter } from "./adapters/index.js";
+export { novadaProxyFetch, validateFetchParams, getCacheTtl, makeCacheKey, clearResponseCache, } from "./tools/fetch.js";
+export type { FetchParams } from "./tools/fetch.js";
+export { novadaProxyBatchFetch, validateBatchFetchParams } from "./tools/batch.js";
+export type { BatchFetchParams, BatchFetchResult } from "./tools/batch.js";
+export { novadaProxySearch, validateSearchParams } from "./tools/search.js";
+export type { SearchParams } from "./tools/search.js";
+export { novadaProxySession, validateSessionParams } from "./tools/session.js";
+export type { SessionParams } from "./tools/session.js";
+export { novadaProxyStatus } from "./tools/status.js";
+export { novadaProxyRender, validateRenderParams } from "./tools/render.js";
+export type { RenderParams } from "./tools/render.js";
+export { novadaProxyExtract, validateExtractParams, extractField, deepFind, shouldEscalateToRender, } from "./tools/extract.js";
+export type { ExtractParams } from "./tools/extract.js";
+export { novadaProxyMap, validateMapParams } from "./tools/map.js";
+export type { MapParams } from "./tools/map.js";
+export { novadaProxyCrawl, validateCrawlParams } from "./tools/crawl.js";
+export type { CrawlParams, CrawlPageResult } from "./tools/crawl.js";
+export { novadaProxyResearch, validateResearchParams } from "./tools/research.js";
+export type { ResearchParams } from "./tools/research.js";
+export { unicodeSafeTruncate, decodeHtmlEntities, htmlToMarkdown, htmlToText, stripNoiseElements, countHtmlTags, contentDensity, } from "./utils.js";
+export { SAFE_COUNTRY, SAFE_CITY, SAFE_SESSION_ID, QUOTA_NOTE } from "./validation.js";
+export { redactCredentials } from "./redact.js";