alterlab-mcp-server 1.6.1 → 1.8.0

package/dist/client.js

@@ -3,22 +3,68 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AlterLabClient = void 0;
 // Read version from package.json at build time is complex with ESM,
 // so we hardcode it and keep in sync with package.json.
-const VERSION = "1.1.0";
+const VERSION = "1.7.1";
 const MAX_RETRIES = 2;
 class AlterLabClient {
     apiKey;
     apiUrl;
     userAgent;
+    sourceHeader;
+    /**
+     * Stores the most recent balance warning parsed from response headers.
+     * Updated after every successful API call. Null when no warning headers
+     * were present in the last response, or before the first call.
+     */
+    _lastBalanceWarning = null;
     constructor(config) {
         this.apiKey = config.apiKey;
         this.apiUrl = config.apiUrl;
         this.userAgent = `alterlab-mcp-server/${VERSION}`;
+        this.sourceHeader = `mcp-server/${VERSION}`;
+    }
+    /**
+     * Returns the balance warning from the most recent API response, or null
+     * if no warning headers were present. Tool handlers call this after each
+     * API request to append a proactive warning when balance is low.
+     */
+    getLastBalanceWarning() {
+        return this._lastBalanceWarning;
+    }
+    /**
+     * Parse X-AlterLab-Balance and X-AlterLab-Balance-Warning headers from an
+     * HTTP response and store the result. Both headers must be present and the
+     * warning level must be 'low', 'critical', or 'exhausted' — otherwise the
+     * stored warning is cleared to null (healthy balance = no warning).
+     */
+    parseBalanceWarningHeaders(response) {
+        const balanceHeader = response.headers.get("X-AlterLab-Balance");
+        const warningHeader = response.headers.get("X-AlterLab-Balance-Warning");
+        if (!balanceHeader || !warningHeader) {
+            this._lastBalanceWarning = null;
+            return;
+        }
+        const level = warningHeader.trim().toLowerCase();
+        if (level !== "low" && level !== "critical" && level !== "exhausted") {
+            // Healthy balance or unknown level — clear warning
+            this._lastBalanceWarning = null;
+            return;
+        }
+        // Parse the dollar amount from the balance header (e.g. '$0.42')
+        const balanceStr = balanceHeader.trim();
+        const parsed = parseFloat(balanceStr.replace(/[^0-9.]/g, ""));
+        const balance_usd = isNaN(parsed) ? null : parsed;
+        this._lastBalanceWarning = {
+            level: level,
+            balance: balanceStr,
+            balance_usd,
+        };
     }
     async request(method, path, body, retryCount = 0) {
         const url = `${this.apiUrl}${path}`;
         const headers = {
             "X-API-Key": this.apiKey,
             "User-Agent": this.userAgent,
+            "X-AlterLab-Source": this.sourceHeader,
             "Content-Type": "application/json",
         };
         const response = await fetch(url, {
@@ -37,6 +83,9 @@ class AlterLabClient {
             return this.request(method, path, body, retryCount + 1);
         }
         if (!response.ok) {
+            // Still parse balance warning headers on error responses — the server may
+            // send them even on 402/4xx to alert about the balance state.
+            this.parseBalanceWarningHeaders(response);
             let detail;
             try {
                 const errorBody = await response.json();
@@ -51,6 +100,8 @@ class AlterLabClient {
             const apiError = { status: response.status, detail };
             throw apiError;
         }
+        // Parse balance warning headers from successful responses
+        this.parseBalanceWarningHeaders(response);
         return (await response.json());
     }
     async scrape(params) {
@@ -62,6 +113,9 @@ class AlterLabClient {
     async getBalance() {
         return this.request("GET", "/api/v1/billing/balance");
     }
+    async getUsage() {
+        return this.request("GET", "/api/v1/billing/usage");
+    }
     async listSessions() {
         return this.request("GET", "/api/v1/sessions/");
     }
@@ -149,6 +203,7 @@ class AlterLabClient {
             headers: {
                 "X-API-Key": this.apiKey,
                 "User-Agent": this.userAgent,
+                "X-AlterLab-Source": this.sourceHeader,
             },
         });
         if (!response.ok) {

package/dist/client.js.map

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

package/dist/config.d.ts

@@ -2,5 +2,25 @@ export interface Config {
     apiKey: string;
     apiUrl: string;
 }
-export declare function loadConfig(): Config;
+/** Path to the user-level AlterLab config file. */
+export declare const CONFIG_FILE_PATH: string;
+/** Base API URL, respecting the ALTERLAB_API_URL override. */
+export declare function getApiUrl(): string;
+/**
+ * Load config from the user-level config file (~/.alterlab/config.json).
+ * Returns null if the file does not exist or does not contain a valid apiKey.
+ */
+export declare function loadConfigFromFile(): Config | null;
+/**
+ * Save the API key to the user-level config file (~/.alterlab/config.json).
+ * Creates the directory if it does not exist.
+ * File is written with mode 0o600 (owner read/write only).
+ */
+export declare function saveConfigToFile(apiKey: string): void;
+/**
+ * Load config from environment variable only.
+ * Returns null instead of exiting when the key is absent —
+ * callers use ensureAuth() for the full fallback chain.
+ */
+export declare function loadConfig(): Config | null;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,UAAU,IAAI,MAAM,CAiBnC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,mDAAmD;AACnD,eAAO,MAAM,gBAAgB,QAI5B,CAAC;AAEF,8DAA8D;AAC9D,wBAAgB,SAAS,IAAI,MAAM,CAKlC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAclD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAKrD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,MAAM,GAAG,IAAI,CAM1C"}

package/dist/config.js

@@ -1,17 +1,94 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_FILE_PATH = void 0;
+exports.getApiUrl = getApiUrl;
+exports.loadConfigFromFile = loadConfigFromFile;
+exports.saveConfigToFile = saveConfigToFile;
 exports.loadConfig = loadConfig;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+/** Path to the user-level AlterLab config file. */
+exports.CONFIG_FILE_PATH = path.join(os.homedir(), ".alterlab", "config.json");
+/** Base API URL, respecting the ALTERLAB_API_URL override. */
+function getApiUrl() {
+    return (process.env.ALTERLAB_API_URL?.replace(/\/+$/, "") ||
+        "https://api.alterlab.io");
+}
+/**
+ * Load config from the user-level config file (~/.alterlab/config.json).
+ * Returns null if the file does not exist or does not contain a valid apiKey.
+ */
+function loadConfigFromFile() {
+    try {
+        if (!fs.existsSync(exports.CONFIG_FILE_PATH)) {
+            return null;
+        }
+        const raw = fs.readFileSync(exports.CONFIG_FILE_PATH, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.apiKey === "string" && parsed.apiKey.length > 0) {
+            return { apiKey: parsed.apiKey, apiUrl: getApiUrl() };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save the API key to the user-level config file (~/.alterlab/config.json).
+ * Creates the directory if it does not exist.
+ * File is written with mode 0o600 (owner read/write only).
+ */
+function saveConfigToFile(apiKey) {
+    const dir = path.dirname(exports.CONFIG_FILE_PATH);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const content = JSON.stringify({ apiKey, apiUrl: getApiUrl() }, null, 2);
+    fs.writeFileSync(exports.CONFIG_FILE_PATH, content, { encoding: "utf-8", mode: 0o600 });
+}
+/**
+ * Load config from environment variable only.
+ * Returns null instead of exiting when the key is absent —
+ * callers use ensureAuth() for the full fallback chain.
+ */
 function loadConfig() {
     const apiKey = process.env.ALTERLAB_API_KEY;
     if (!apiKey) {
-        console.error("Error: ALTERLAB_API_KEY environment variable is required.\n\n" +
-            "Get your API key at https://alterlab.io/dashboard/api-keys\n\n" +
-            "Then add it to your MCP config:\n" +
-            '  "env": { "ALTERLAB_API_KEY": "sk_live_..." }');
-        process.exit(1);
+        return null;
     }
-    const apiUrl = process.env.ALTERLAB_API_URL?.replace(/\/+$/, "") ||
-        "https://api.alterlab.io";
-    return { apiKey, apiUrl };
+    return { apiKey, apiUrl: getApiUrl() };
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;AAKA,gCAiBC;AAjBD,SAAgB,UAAU;IACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC5C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CACX,+DAA+D;YAC7D,gEAAgE;YAChE,mCAAmC;YACnC,gDAAgD,CACnD,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GACV,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACjD,yBAAyB,CAAC;IAE5B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiBA,8BAKC;AAMD,gDAcC;AAOD,4CAKC;AAOD,gCAMC;AAnED,uCAAyB;AACzB,2CAA6B;AAC7B,uCAAyB;AAOzB,mDAAmD;AACtC,QAAA,gBAAgB,GAAG,IAAI,CAAC,IAAI,CACvC,EAAE,CAAC,OAAO,EAAE,EACZ,WAAW,EACX,aAAa,CACd,CAAC;AAEF,8DAA8D;AAC9D,SAAgB,SAAS;IACvB,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QACjD,yBAAyB,CAC1B,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,kBAAkB;IAChC,IAAI,CAAC;QACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,wBAAgB,CAAC,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,wBAAgB,EAAE,OAAO,CAAC,CAAC;QACvD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;QAC1D,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC;QACxD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,MAAc;IAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,wBAAgB,CAAC,CAAC;IAC3C,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IACzE,EAAE,CAAC,aAAa,CAAC,wBAAgB,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAClF,CAAC;AAED;;;;GAIG;AACH,SAAgB,UAAU;IACxB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC5C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC;AACzC,CAAC"}

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,QAAQ,GAAG,KAAK,EACvB,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACzB,cAAc,CAuJhB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,QAAQ,GAAG,KAAK,EACvB,OAAO,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACzB,cAAc,CA4KhB"}

package/dist/errors.js

@@ -83,10 +83,12 @@ function formatErrorResult(error, context) {
                     {
                         type: "text",
                         text: `Access denied${url}: ${detail}\n\n` +
-                            "The site may have blocked the request. Suggested actions:\n" +
-                            "- Try with `render_js: true` to use a headless browser\n" +
-                            "- Try with `use_proxy: true` to route through a premium proxy\n" +
-                            "- Some sites may not be scrapable",
+                            "The site blocked this request. Suggested actions:\n" +
+                            "- Try `render_js: true` — headless browser bypass (escalates to tier 4, ~$0.001/req)\n" +
+                            "- Try `use_proxy: true` — premium proxy rotation (+~$0.0002/req)\n" +
+                            "- Try both together (`render_js: true, use_proxy: true`) for maximum bypass capability\n" +
+                            "- Use `alterlab_estimate_cost` to preview cost before retrying\n" +
+                            "- Some sites actively block all scrapers and cannot be scraped",
                     },
                 ],
             };
@@ -112,7 +114,24 @@ function formatErrorResult(error, context) {
                     },
                 ],
             };
-        case 504:
+        case 504: {
+            // The API returns credits_status and estimated_completion_s in the 504 body
+            let creditsNote = "";
+            let completionNote = "";
+            try {
+                if (detail) {
+                    const parsed = JSON.parse(detail);
+                    if (parsed.credits_status) {
+                        creditsNote = `\nCredits: ${parsed.credits_status}`;
+                    }
+                    if (parsed.estimated_completion_s) {
+                        completionNote = `\nEstimated completion: ~${parsed.estimated_completion_s}s`;
+                    }
+                }
+            }
+            catch {
+                // detail is plain text, not JSON — use default messaging
+            }
             return {
                 isError: true,
                 content: [
@@ -121,10 +140,13 @@ function formatErrorResult(error, context) {
                         text: `Gateway timeout${url}.\n\n` +
                             "The scraping job may still be running on the server.\n" +
                             "Do NOT retry immediately — credits may have been consumed.\n" +
-                            "Wait and check your balance before retrying.",
+                            "Wait and check your balance before retrying." +
+                            creditsNote +
+                            completionNote,
                     },
                 ],
             };
+        }
         default:
             return {
                 isError: true,

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;AAQA,8CA0JC;AA1JD,SAAgB,iBAAiB,CAC/B,KAAuB,EACvB,OAA0B;IAE1B,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,yBAAyB;QACzB,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtD,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACrE,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EACF,oBAAoB,GAAG,OAAO;4BAC9B,sBAAsB;4BACtB,iDAAiD;4BACjD,4DAA4D;4BAC5D,sDAAsD;qBACzD;iBACF;aACF,CAAC;QACJ,CAAC;QACD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,iBAAiB,GAAG,KAAK,KAAK,CAAC,OAAO,EAAE;iBAC/C;aACF;SACF,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG;QACnB,CAAC,CAAC,QAAQ,KAAK,CAAC,GAAG,EAAE;QACrB,CAAC,CAAC,OAAO,EAAE,GAAG;YACZ,CAAC,CAAC,QAAQ,OAAO,CAAC,GAAG,EAAE;YACvB,CAAC,CAAC,EAAE,CAAC;IACT,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,eAAe,CAAC;IAE/C,QAAQ,KAAK,CAAC,MAAM,EAAE,CAAC;QACrB,KAAK,GAAG;YACN,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EACF,cAAc,GAAG,KAAK,MAAM,MAAM;4BAClC,sDAAsD;4BACtD,wBAAwB;4BACxB,sCAAsC;qBACzC;iBACF;aACF,CAAC;QAEJ,KAAK,GAAG;YACN,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EACF,6CAA6C;4BAC7C,iDAAiD;4BACjD,0DAA0D;qBAC7D;iBACF;aACF,CAAC;QAEJ,KAAK,GAAG;YACN,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EACF,uBAAuB,GAAG,KAAK,MAAM,MAAM;4BAC3C,sBAAsB;4BACtB,8DAA8D;4BAC9D,yDAAyD;4BACzD,+DAA+D;qBAClE;iBACF;aACF,CAAC;QAEJ,KAAK,GAAG;YACN,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EACF,gBAAgB,GAAG,KAAK,MAAM,MAAM;4BACpC,6DAA6D;4BAC7D,0DAA0D;4BAC1D,iEAAiE;4BACjE,mCAAmC;qBACtC;iBACF;aACF,CAAC;QAEJ,KAAK,GAAG;YACN,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,mBAAmB,GAAG,KAAK,MAAM,EAAE;qBAC1C;iBACF;aACF,CAAC;QAEJ,KAAK,GAAG;YACN,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EACF,eAAe,GAAG,OAAO;4BACzB,mDAAmD;4BACnD,yDAAyD;qBAC5D;iBACF;aACF,CAAC;QAEJ,KAAK,GAAG;YACN,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EACF,kBAAkB,GAAG,OAAO;4BAC5B,wDAAwD;4BACxD,8DAA8D;4BAC9D,8CAA8C;qBACjD;iBACF;aACF,CAAC;QAEJ;YACE,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAM;wBACZ,IAAI,EAAE,cAAc,KAAK,CAAC,MAAM,IAAI,GAAG,KAAK,MAAM,EAAE;qBACrD;iBACF;aACF,CAAC;IACN,CAAC;AACH,CAAC"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/format.d.ts

@@ -1,4 +1,4 @@
-import { type BalanceResponse, type BetaFeatureListResponse, type BetaFeatureMyResponse, type BetaFeatureToggleResponse, type CostEstimate, type SessionCreateResponse, type SessionDetailResponse, type SessionListResponse, type SessionValidateResponse, type UnifiedScrapeResponse } from "./types.js";
+import { type BalanceResponse, type BalanceWarning, type BetaFeatureListResponse, type BetaFeatureMyResponse, type BetaFeatureToggleResponse, type CostEstimate, type SessionCreateResponse, type SessionDetailResponse, type SessionListResponse, type SessionValidateResponse, type UnifiedScrapeResponse } from "./types.js";
 /**
  * Format a scrape response as LLM-optimized markdown.
  * Returns primary content + a compact metadata footer.
@@ -8,14 +8,28 @@ export declare function formatScrapeResponse(response: UnifiedScrapeResponse): s
  * Format an extraction response — structured JSON as markdown code block.
  */
 export declare function formatExtractResponse(response: UnifiedScrapeResponse): string;
+/**
+ * Format a cost estimate as a compact inline header (one line).
+ * Used by estimate_first in alterlab_scrape to prepend before scrape results.
+ */
+export declare function formatEstimateInline(estimate: CostEstimate): string;
 /**
  * Format a cost estimate as readable text.
  */
 export declare function formatEstimateResponse(estimate: CostEstimate): string;
 /**
- * Format a balance response as readable text.
+ * Format a balance response as readable text, including balance status and
+ * estimated runway (days at current spending rate).
  */
 export declare function formatBalanceResponse(balance: BalanceResponse): string;
+/**
+ * Format a balance warning from response headers into a human-readable suffix.
+ *
+ * Returns a non-empty string (starting with a newline) when the balance is
+ * low, critical, or exhausted. Returns an empty string when warning is null
+ * (healthy balance — no suffix appended).
+ */
+export declare function formatBalanceWarning(warning: BalanceWarning | null): string;
 /**
  * Format a session list response as readable text.
  */

package/dist/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CAsF5E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CA2C7E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAarE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAWtE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,mBAAmB,GAC5B,MAAM,CAkCR;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,uBAAuB,GAChC,MAAM,CAsBR;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CA4CR;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CAUR;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CAWR;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,uBAAuB,GAChC,MAAM,CAgCR;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CAgBR;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,yBAAyB,GAClC,MAAM,CAQR"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,YAAY,EACjB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC3B,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CA6L5E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,CA2C7E;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAQnE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAarE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAiCtE;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,MAAM,CAuB3E;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,mBAAmB,GAC5B,MAAM,CAkCR;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,uBAAuB,GAChC,MAAM,CAsBR;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CA4CR;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CAUR;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CAWR;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,uBAAuB,GAChC,MAAM,CAgCR;AAED;;GAEG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CAgBR;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,yBAAyB,GAClC,MAAM,CAQR"}

package/dist/format.js

@@ -2,8 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatScrapeResponse = formatScrapeResponse;
 exports.formatExtractResponse = formatExtractResponse;
+exports.formatEstimateInline = formatEstimateInline;
 exports.formatEstimateResponse = formatEstimateResponse;
 exports.formatBalanceResponse = formatBalanceResponse;
+exports.formatBalanceWarning = formatBalanceWarning;
 exports.formatSessionListResponse = formatSessionListResponse;
 exports.formatSessionCreateResponse = formatSessionCreateResponse;
 exports.formatSessionValidateResponse = formatSessionValidateResponse;
@@ -67,6 +69,24 @@ function formatScrapeResponse(response) {
     else if (typeof content === "string") {
         parts.push(content);
     }
+    // LLM extraction result (from extraction_schema or extraction_prompt)
+    if (response.extraction_result && !hasFilteredContent) {
+        parts.push("\n**Extraction Result**\n```json\n" +
+            JSON.stringify(response.extraction_result, null, 2) +
+            "\n```");
+    }
+    // Browser action results (from advanced.actions)
+    if (response.action_results && response.action_results.length > 0) {
+        const actionSummary = response.action_results
+            .map((a, i) => {
+            const status = a.success ? "ok" : "failed";
+            const type = String(a.type ?? "action");
+            const result = a.result ? ` → ${String(a.result)}` : "";
+            return `  ${i + 1}. [${status}] ${type}${result}`;
+        })
+            .join("\n");
+        parts.push(`\n**Action Results**\n${actionSummary}`);
+    }
     // Metadata footer
     const tier = response.billing.tier_used;
     const tierName = types_js_1.TIER_NAMES[tier] || tier;
@@ -74,21 +94,84 @@ function formatScrapeResponse(response) {
     const cost = response.billing.final_cost_microcents
         ? `$${(response.billing.final_cost_microcents / 1_000_000).toFixed(6)}`
         : `${response.billing.total_credits} credits`;
+    const sourceUrl = response.redirected && response.final_url
+        ? `${response.url} → ${response.final_url}`
+        : response.url;
     parts.push("\n---\n" +
-        `Source: ${response.url} | ` +
+        `Source: ${sourceUrl} | ` +
         `Tier: ${tierName} (${tierPrice}/req) | ` +
         `Cost: ${cost} | ` +
         `Time: ${response.response_time_ms}ms` +
-        (response.cached ? " | Cached" : ""));
+        (response.cached ? " | Cached" : "") +
+        (response.billing.byop_applied ? " | BYOP" : ""));
+    if (response.redirect_chain && response.redirect_chain.length > 0) {
+        const chain = response.redirect_chain
+            .map((hop) => `${hop.status_code} → ${hop.url}`)
+            .join("\n  ");
+        parts.push(`Redirect chain:\n  ${chain}`);
+    }
+    if (response.billing.escalations &&
+        response.billing.escalations.length > 1) {
+        const escalationSummary = response.billing.escalations
+            .map((e) => {
+            const tierLabel = types_js_1.TIER_NAMES[e.tier] || e.tier;
+            const durationLabel = e.duration_ms ? ` (${e.duration_ms}ms)` : "";
+            return `${tierLabel}: ${e.result}${durationLabel}`;
+        })
+            .join(" → ");
+        parts.push(`Escalation path: ${escalationSummary}`);
+    }
     if (response.billing.optimization_suggestion) {
         parts.push(`Tip: ${response.billing.optimization_suggestion}`);
     }
+    // API warning messages — surface all warning variants
+    if (response.warning) {
+        parts.push(`Warning: ${response.warning}`);
+    }
+    if (response.domain_warning) {
+        let detail = "";
+        if (response.domain_difficulty) {
+            const d = response.domain_difficulty;
+            const rate = d.success_rate !== undefined
+                ? ` (success rate: ${(Number(d.success_rate) * 100).toFixed(0)}%)`
+                : "";
+            detail = rate;
+        }
+        parts.push(`Domain Warning: ${response.domain_warning}${detail}`);
+    }
+    if (response.tier_cap_warning) {
+        const w = response.tier_cap_warning;
+        const domainMin = w.domain_min_tier !== undefined
+            ? ` Domain requires tier ${w.domain_min_tier}.`
+            : "";
+        if (w.your_max_tier !== undefined) {
+            parts.push(`Tier Cap Warning: Your max_tier (${w.your_max_tier}) is below the domain minimum.${domainMin}`);
+        }
+        else if (w.your_force_tier !== undefined) {
+            parts.push(`Tier Cap Warning: Your force_tier (${w.your_force_tier}) is below the domain minimum.${domainMin}`);
+        }
+    }
     if (response.content_truncated) {
         const t = response.content_truncated;
         const truncatedMB = (t.truncated_at_bytes / 1_048_576).toFixed(1);
         const originalMB = (t.original_size_bytes / 1_048_576).toFixed(1);
-        parts.push(`Warning: Content truncated at ${truncatedMB} MB (original: ${originalMB} MB, reason: ${t.truncation_reason}). ` +
-            `Increase max_response_bytes or use a more targeted selector to capture the full page.`);
+        const truncationPrefix = `Warning: Content truncated at ${truncatedMB} MB (original: ${originalMB} MB, reason: ${t.truncation_reason}). `;
+        if (t.truncation_reason === "response_body_cap") {
+            parts.push(truncationPrefix +
+                `Increase max_response_bytes or use a more targeted selector to capture the full page.`);
+        }
+        else {
+            // readability_input_cap or readability_output_cap — server-side caps that
+            // max_response_bytes cannot affect. Advising users to increase it would be misleading.
+            parts.push(truncationPrefix +
+                `This is a server-side readability cap and cannot be raised via max_response_bytes. ` +
+                `Use a more targeted CSS selector to reduce the content region size.`);
+        }
+    }
+    if (response.quality_warning) {
+        const qw = response.quality_warning;
+        parts.push(`Quality warning: ${qw.reason} (code: ${qw.code}, word_count: ${qw.word_count}). ` +
+            `Content was delivered but may contain anti-bot artifacts.`);
     }
     return parts.join("\n");
 }
@@ -128,6 +211,16 @@ function formatExtractResponse(response) {
         `Time: ${response.response_time_ms}ms`);
     return parts.join("\n");
 }
+/**
+ * Format a cost estimate as a compact inline header (one line).
+ * Used by estimate_first in alterlab_scrape to prepend before scrape results.
+ */
+function formatEstimateInline(estimate) {
+    const tierName = types_js_1.TIER_NAMES[estimate.estimated_tier] || estimate.estimated_tier;
+    const tierPrice = types_js_1.TIER_PRICES[estimate.estimated_tier] || "unknown";
+    return (`> **Pre-flight estimate**: ${tierPrice}/req (${tierName}, tier ${estimate.estimated_tier}) — ` +
+        `confidence: ${estimate.confidence}. ${estimate.reasoning}\n`);
+}
 /**
  * Format a cost estimate as readable text.
  */
@@ -142,16 +235,67 @@ function formatEstimateResponse(estimate) {
         `${estimate.reasoning}`);
 }
 /**
- * Format a balance response as readable text.
+ * Format a balance response as readable text, including balance status and
+ * estimated runway (days at current spending rate).
  */
 function formatBalanceResponse(balance) {
     const deposited = (balance.total_deposited_cents / 100).toFixed(2);
     const spent = (balance.total_spent_cents / 100).toFixed(2);
-    return (`**Account Balance**\n\n` +
-        `- Balance: **${balance.balance_display}**\n` +
-        `- Total deposited: $${deposited}\n` +
-        `- Total spent: $${spent}\n\n` +
-        `Add funds: https://alterlab.io/dashboard/billing`);
+    const balanceUsd = balance.balance_microcents / 1_000_000;
+    // Balance status classification
+    let status;
+    if (balanceUsd <= 0) {
+        status = "Exhausted — top up to continue scraping";
+    }
+    else if (balanceUsd < 0.10) {
+        status = "Critical (< $0.10)";
+    }
+    else if (balanceUsd < 0.50) {
+        status = "Low (< $0.50)";
+    }
+    else {
+        status = "Healthy";
+    }
+    // Estimated runway: days at current average daily spend rate.
+    // Uses total_spent_cents as a proxy for lifetime spend, but since we don't
+    // know the account age, we can only compute runway if daily spend is
+    // non-zero. The balance endpoint doesn't expose daily spend directly, so
+    // we skip runway here and recommend alterlab_get_usage for that detail.
+    const lines = [
+        `**Account Balance**\n`,
+        `- Balance: **${balance.balance_display}**`,
+        `- Status: ${status}`,
+        `- Total deposited: $${deposited}`,
+        `- Total spent: $${spent}`,
+        `\nFor spending breakdown and estimated runway: use \`alterlab_get_usage\``,
+        `Add funds: https://alterlab.io/dashboard/billing`,
+    ];
+    return lines.join("\n");
+}
+/**
+ * Format a balance warning from response headers into a human-readable suffix.
+ *
+ * Returns a non-empty string (starting with a newline) when the balance is
+ * low, critical, or exhausted. Returns an empty string when warning is null
+ * (healthy balance — no suffix appended).
+ */
+function formatBalanceWarning(warning) {
+    if (!warning)
+        return "";
+    const fundUrl = "https://alterlab.io/dashboard/billing";
+    switch (warning.level) {
+        case "exhausted":
+            return (`\n\n> **Balance exhausted**: ${warning.balance} remaining. ` +
+                `Add funds to continue scraping: ${fundUrl}`);
+        case "critical":
+            return (`\n\n> **Critical balance**: ${warning.balance} remaining. ` +
+                `Top up soon to avoid interruptions: ${fundUrl}`);
+        case "low":
+            return (`\n\n> **Low balance**: ${warning.balance} remaining. ` +
+                `Add funds: ${fundUrl}`);
+        default:
+            return "";
+    }
 }
 /**
  * Format a session list response as readable text.