@spider-cloud/spider-client 0.1.84 → 0.1.87

package/README.md

@@ -93,8 +93,68 @@ app.crawlUrl(url, crawlParams, stream, streamCallback);
 - **`links(url, params)`**: Retrieve all links from the specified URL with optional parameters.
 - **`screenshot(url, params)`**: Take a screenshot of the specified URL.
 - **`transform(data, params)`**: Perform a fast HTML transformation to markdown or text.
+- **`unblocker(url, params)`**: Unblock challenging websites with anti-bot bypass. Supports AI extraction with `custom_prompt`.
 - **`getCredits()`**: Retrieve account's remaining credits.
 
+### AI Studio Methods
+
+AI Studio methods require an active AI Studio subscription.
+
+- **`aiCrawl(url, prompt, params)`**: AI-guided crawling using natural language prompts.
+- **`aiScrape(url, prompt, params)`**: AI-guided scraping using natural language prompts.
+- **`aiSearch(prompt, params)`**: AI-enhanced web search using natural language queries.
+- **`aiBrowser(url, prompt, params)`**: AI-guided browser automation using natural language commands.
+- **`aiLinks(url, prompt, params)`**: AI-guided link extraction and filtering.
+
+```javascript
+// AI Scrape example
+const result = await app.aiScrape(
+  "https://example.com/products",
+  "Extract all product names, prices, and descriptions"
+);
+```
+
+### Unblocker with AI Extraction
+
+```javascript
+// Unblock and extract data using AI
+const result = await app.unblocker("https://protected-site.com/products", {
+  custom_prompt: "Extract all product names and prices as JSON"
+});
+// Extracted data is available in result[0].metadata.extracted_data
+```
+
+### Unblocker with JSON Schema Extraction
+
+Use JSON Schema for structured, validated extraction output:
+
+```javascript
+const result = await app.unblocker("https://protected-site.com/products", {
+  extraction_schema: {
+    name: "products",
+    description: "Product listing extraction",
+    schema: JSON.stringify({
+      type: "object",
+      properties: {
+        products: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string" },
+              price: { type: "number" }
+            },
+            required: ["name", "price"]
+          }
+        }
+      }
+    }),
+    strict: true
+  }
+});
+// Extracted data conforms to the schema in result[0].metadata.extracted_data
+```
+
 ## Error Handling
 
 The SDK provides robust error handling and will throw exceptions when it encounters critical issues. Always use `.catch()` on promises to handle these errors gracefully.

package/dist/client.d.ts

@@ -1,4 +1,15 @@
-import { ChunkCallbackFunction, Collection, SpiderCoreResponse, SpiderParams, SearchRequestParams, RequestParamsTransform } from "./config";
+import { ChunkCallbackFunction, Collection, SpiderCoreResponse, SpiderParams, SearchRequestParams, RequestParamsTransform, AIRequestParams, AIStudioTier } from "./config";
+/**
+ * Rate limit state from API response headers.
+ */
+export interface RateLimitInfo {
+    /** Maximum requests allowed per minute. */
+    limit: number;
+    /** Requests remaining in the current window. */
+    remaining: number;
+    /** Seconds until the rate limit window resets. */
+    resetSeconds: number;
+}
 /**
  * Generic params for core request.
  */
@@ -14,12 +25,28 @@ export interface SpiderConfig {
  */
 export declare class Spider {
     private apiKey?;
+    private aiRateLimiter;
+    private aiStudioTier;
+    /** The latest rate limit state from API response headers. */
+    rateLimit: RateLimitInfo;
     /**
      * Create an instance of Spider.
      * @param {string | null} apiKey - The API key used to authenticate to the Spider API. If null, attempts to source from environment variables.
+     * @param {AIStudioTier} aiStudioTier - The AI Studio subscription tier for rate limiting. Defaults to 'starter'.
      * @throws Will throw an error if the API key is not provided.
      */
-    constructor(props?: SpiderConfig);
+    constructor(props?: SpiderConfig & {
+        aiStudioTier?: AIStudioTier;
+    });
+    /**
+     * Update the AI Studio subscription tier (adjusts rate limiting).
+     * @param {AIStudioTier} tier - The new subscription tier.
+     */
+    setAIStudioTier(tier: AIStudioTier): void;
+    /**
+     * Update rate limit state from response headers.
+     */
+    private _updateRateLimit;
     /**
      * Internal method to handle POST requests.
      * @param {string} endpoint - The API endpoint to which the POST request should be sent.
@@ -66,6 +93,13 @@ export declare class Spider {
      * @returns {Promise<any>} The screenshot data.
      */
     screenshot(url: string, params?: GenericParams): Promise<any>;
+    /**
+     * Unblock a challenging url to get data.
+     * @param {string} url - The URL to get data from.
+     * @param {GenericParams} [params={}] - Configuration parameters for the screenshot.
+     * @returns {Promise<any>} The screenshot data.
+     */
+    unblocker(url: string, params?: GenericParams): Promise<any>;
     /**
      *  Perform a search and gather a list of websites to start crawling and collect resources.
      * @param {string} search - The search query.
@@ -113,6 +147,64 @@ export declare class Spider {
         Authorization: string;
         "User-Agent": string;
     };
+    /**
+     * Internal method to handle AI Studio POST requests with rate limiting.
+     * @param {string} endpoint - The AI Studio endpoint.
+     * @param {Record<string, any>} data - The request data including prompt.
+     * @returns {Promise<any>} The response data.
+     * @throws {AIStudioSubscriptionRequired} When subscription is not active.
+     * @throws {AIStudioRateLimitExceeded} When rate limit is exceeded server-side.
+     */
+    private _aiApiPost;
+    /**
+     * AI-guided crawling using natural language prompts.
+     * Requires an active AI Studio subscription.
+     * @param {string} url - The URL to start crawling.
+     * @param {string} prompt - Natural language instruction for what to crawl and extract.
+     * @param {AIRequestParams} [params={}] - Additional parameters for the crawl.
+     * @returns {Promise<any>} The crawl results guided by the AI prompt.
+     * @throws {AIStudioSubscriptionRequired} When subscription is not active.
+     */
+    aiCrawl(url: string, prompt: string, params?: Omit<AIRequestParams, "prompt">): Promise<any>;
+    /**
+     * AI-guided scraping using natural language prompts.
+     * Requires an active AI Studio subscription.
+     * @param {string} url - The URL to scrape.
+     * @param {string} prompt - Natural language description of data to extract.
+     * @param {AIRequestParams} [params={}] - Additional parameters for the scrape.
+     * @returns {Promise<any>} The scraped data guided by the AI prompt.
+     * @throws {AIStudioSubscriptionRequired} When subscription is not active.
+     */
+    aiScrape(url: string, prompt: string, params?: Omit<AIRequestParams, "prompt">): Promise<any>;
+    /**
+     * AI-enhanced web search using natural language queries.
+     * Requires an active AI Studio subscription.
+     * @param {string} prompt - Natural language search query.
+     * @param {SearchRequestParams} [params={}] - Additional search parameters.
+     * @returns {Promise<any>} The search results with AI-enhanced relevance.
+     * @throws {AIStudioSubscriptionRequired} When subscription is not active.
+     */
+    aiSearch(prompt: string, params?: SearchRequestParams): Promise<any>;
+    /**
+     * AI-guided browser automation using natural language commands.
+     * Requires an active AI Studio subscription.
+     * @param {string} url - The URL to automate.
+     * @param {string} prompt - Natural language description of browser actions.
+     * @param {AIRequestParams} [params={}] - Additional parameters for automation.
+     * @returns {Promise<any>} The automation results.
+     * @throws {AIStudioSubscriptionRequired} When subscription is not active.
+     */
+    aiBrowser(url: string, prompt: string, params?: Omit<AIRequestParams, "prompt">): Promise<any>;
+    /**
+     * AI-guided link extraction and filtering.
+     * Requires an active AI Studio subscription.
+     * @param {string} url - The URL to extract links from.
+     * @param {string} prompt - Natural language description of what links to find.
+     * @param {AIRequestParams} [params={}] - Additional parameters.
+     * @returns {Promise<any>} The filtered links based on AI analysis.
+     * @throws {AIStudioSubscriptionRequired} When subscription is not active.
+     */
+    aiLinks(url: string, prompt: string, params?: Omit<AIRequestParams, "prompt">): Promise<any>;
     /**
      * Handles errors from API requests.
      * @param {Response} response - The fetch response object.

package/dist/client.js

@@ -5,6 +5,50 @@ const config_1 = require("./config");
 const package_json_1 = require("../package.json");
 const stream_reader_1 = require("./utils/stream-reader");
 const exponential_backoff_1 = require("exponential-backoff");
+/**
+ * Simple client-side rate limiter for AI Studio endpoints.
+ * Uses a sliding window approach to limit requests per second.
+ */
+class RateLimiter {
+    constructor(requestsPerSecond) {
+        this.timestamps = [];
+        this.maxRequests = requestsPerSecond;
+        this.windowMs = 1000;
+    }
+    /**
+     * Update the rate limit (e.g., when user tier changes).
+     */
+    setLimit(requestsPerSecond) {
+        this.maxRequests = requestsPerSecond;
+    }
+    /**
+     * Check if a request can be made. If not, returns the ms to wait.
+     * If yes, records the request and returns 0.
+     */
+    tryAcquire() {
+        const now = Date.now();
+        // Remove timestamps outside the window
+        this.timestamps = this.timestamps.filter((t) => now - t < this.windowMs);
+        if (this.timestamps.length >= this.maxRequests) {
+            // Calculate how long to wait
+            const oldestInWindow = this.timestamps[0];
+            const waitTime = this.windowMs - (now - oldestInWindow);
+            return Math.max(1, waitTime);
+        }
+        this.timestamps.push(now);
+        return 0;
+    }
+    /**
+     * Wait until a request can be made, then acquire the slot.
+     */
+    async acquire() {
+        const waitTime = this.tryAcquire();
+        if (waitTime > 0) {
+            await new Promise((resolve) => setTimeout(resolve, waitTime));
+            return this.acquire();
+        }
+    }
+}
 /**
  * A class to interact with the Spider API.
  */
@@ -12,15 +56,42 @@ class Spider {
     /**
      * Create an instance of Spider.
      * @param {string | null} apiKey - The API key used to authenticate to the Spider API. If null, attempts to source from environment variables.
+     * @param {AIStudioTier} aiStudioTier - The AI Studio subscription tier for rate limiting. Defaults to 'starter'.
      * @throws Will throw an error if the API key is not provided.
      */
     constructor(props) {
         var _a;
+        /** The latest rate limit state from API response headers. */
+        this.rateLimit = { limit: 0, remaining: 0, resetSeconds: 0 };
         this.apiKey = (props === null || props === void 0 ? void 0 : props.apiKey) || ((_a = process === null || process === void 0 ? void 0 : process.env) === null || _a === void 0 ? void 0 : _a.SPIDER_API_KEY);
+        this.aiStudioTier = (props === null || props === void 0 ? void 0 : props.aiStudioTier) || "starter";
+        this.aiRateLimiter = new RateLimiter(config_1.AI_STUDIO_RATE_LIMITS[this.aiStudioTier]);
         if (!this.apiKey) {
             throw new Error("No API key provided");
         }
     }
+    /**
+     * Update the AI Studio subscription tier (adjusts rate limiting).
+     * @param {AIStudioTier} tier - The new subscription tier.
+     */
+    setAIStudioTier(tier) {
+        this.aiStudioTier = tier;
+        this.aiRateLimiter.setLimit(config_1.AI_STUDIO_RATE_LIMITS[tier]);
+    }
+    /**
+     * Update rate limit state from response headers.
+     */
+    _updateRateLimit(headers) {
+        const limit = headers.get("RateLimit-Limit");
+        const remaining = headers.get("RateLimit-Remaining");
+        const reset = headers.get("RateLimit-Reset");
+        if (limit)
+            this.rateLimit.limit = Number(limit);
+        if (remaining)
+            this.rateLimit.remaining = Number(remaining);
+        if (reset)
+            this.rateLimit.resetSeconds = Number(reset);
+    }
     /**
      * Internal method to handle POST requests.
      * @param {string} endpoint - The API endpoint to which the POST request should be sent.
@@ -30,11 +101,20 @@ class Spider {
      */
     async _apiPost(endpoint, data, stream, jsonl) {
         const headers = jsonl ? this.prepareHeadersJsonL : this.prepareHeaders;
-        const response = await (0, exponential_backoff_1.backOff)(() => fetch(`${config_1.APISchema["url"]}/${config_1.ApiVersion.V1}/${endpoint}`, {
-            method: "POST",
-            headers: headers,
-            body: JSON.stringify(data),
-        }), {
+        const response = await (0, exponential_backoff_1.backOff)(async () => {
+            const res = await fetch(`${config_1.APISchema["url"]}/${config_1.ApiVersion.V1}/${endpoint}`, {
+                method: "POST",
+                headers: headers,
+                body: JSON.stringify(data),
+            });
+            this._updateRateLimit(res.headers);
+            if (res.status === 429) {
+                const retryAfter = Number(res.headers.get("Retry-After") || "1");
+                await new Promise((r) => setTimeout(r, retryAfter * 1000));
+                throw new Error(`Rate limited on ${endpoint}. Retrying after ${retryAfter}s.`);
+            }
+            return res;
+        }, {
             numOfAttempts: 5,
         });
         if (!stream) {
@@ -54,10 +134,19 @@ class Spider {
      */
     async _apiGet(endpoint) {
         const headers = this.prepareHeaders;
-        const response = await (0, exponential_backoff_1.backOff)(() => fetch(`${config_1.APISchema["url"]}/${config_1.ApiVersion.V1}/${endpoint}`, {
-            method: "GET",
-            headers: headers,
-        }), {
+        const response = await (0, exponential_backoff_1.backOff)(async () => {
+            const res = await fetch(`${config_1.APISchema["url"]}/${config_1.ApiVersion.V1}/${endpoint}`, {
+                method: "GET",
+                headers: headers,
+            });
+            this._updateRateLimit(res.headers);
+            if (res.status === 429) {
+                const retryAfter = Number(res.headers.get("Retry-After") || "1");
+                await new Promise((r) => setTimeout(r, retryAfter * 1000));
+                throw new Error(`Rate limited on ${endpoint}. Retrying after ${retryAfter}s.`);
+            }
+            return res;
+        }, {
             numOfAttempts: 5,
         });
         if (response.ok) {
@@ -117,6 +206,15 @@ class Spider {
     async screenshot(url, params = {}) {
         return this._apiPost(config_1.APIRoutes.Screenshot, { url: url, ...params });
     }
+    /**
+     * Unblock a challenging url to get data.
+     * @param {string} url - The URL to get data from.
+     * @param {GenericParams} [params={}] - Configuration parameters for the screenshot.
+     * @returns {Promise<any>} The screenshot data.
+     */
+    async unblocker(url, params = {}) {
+        return this._apiPost(config_1.APIRoutes.Unblocker, { url: url, ...params });
+    }
     /**
      *  Perform a search and gather a list of websites to start crawling and collect resources.
      * @param {string} search - The search query.
@@ -178,6 +276,102 @@ class Spider {
             "Content-Type": "application/jsonl",
         };
     }
+    /**
+     * Internal method to handle AI Studio POST requests with rate limiting.
+     * @param {string} endpoint - The AI Studio endpoint.
+     * @param {Record<string, any>} data - The request data including prompt.
+     * @returns {Promise<any>} The response data.
+     * @throws {AIStudioSubscriptionRequired} When subscription is not active.
+     * @throws {AIStudioRateLimitExceeded} When rate limit is exceeded server-side.
+     */
+    async _aiApiPost(endpoint, data) {
+        // Apply client-side rate limiting
+        await this.aiRateLimiter.acquire();
+        const headers = this.prepareHeaders;
+        const response = await (0, exponential_backoff_1.backOff)(() => fetch(`${config_1.APISchema["url"]}/${config_1.ApiVersion.V1}/${endpoint}`, {
+            method: "POST",
+            headers: headers,
+            body: JSON.stringify(data),
+        }), {
+            numOfAttempts: 3,
+            retry: (e, attemptNumber) => {
+                // Don't retry on subscription or rate limit errors
+                return attemptNumber < 3;
+            },
+        });
+        if (response.ok) {
+            return response.json();
+        }
+        // Handle AI Studio specific errors
+        if (response.status === 402) {
+            throw new config_1.AIStudioSubscriptionRequired();
+        }
+        if (response.status === 429) {
+            const retryAfter = response.headers.get("Retry-After");
+            const retryAfterMs = retryAfter ? parseInt(retryAfter) * 1000 : 1000;
+            throw new config_1.AIStudioRateLimitExceeded(retryAfterMs);
+        }
+        this.handleError(response, `AI request to ${endpoint}`);
+    }
+    /**
+     * AI-guided crawling using natural language prompts.
+     * Requires an active AI Studio subscription.
+     * @param {string} url - The URL to start crawling.
+     * @param {string} prompt - Natural language instruction for what to crawl and extract.
+     * @param {AIRequestParams} [params={}] - Additional parameters for the crawl.
+     * @returns {Promise<any>} The crawl results guided by the AI prompt.
+     * @throws {AIStudioSubscriptionRequired} When subscription is not active.
+     */
+    async aiCrawl(url, prompt, params = {}) {
+        return this._aiApiPost(config_1.APIRoutes.AICrawl, { url, prompt, ...params });
+    }
+    /**
+     * AI-guided scraping using natural language prompts.
+     * Requires an active AI Studio subscription.
+     * @param {string} url - The URL to scrape.
+     * @param {string} prompt - Natural language description of data to extract.
+     * @param {AIRequestParams} [params={}] - Additional parameters for the scrape.
+     * @returns {Promise<any>} The scraped data guided by the AI prompt.
+     * @throws {AIStudioSubscriptionRequired} When subscription is not active.
+     */
+    async aiScrape(url, prompt, params = {}) {
+        return this._aiApiPost(config_1.APIRoutes.AIScrape, { url, prompt, ...params });
+    }
+    /**
+     * AI-enhanced web search using natural language queries.
+     * Requires an active AI Studio subscription.
+     * @param {string} prompt - Natural language search query.
+     * @param {SearchRequestParams} [params={}] - Additional search parameters.
+     * @returns {Promise<any>} The search results with AI-enhanced relevance.
+     * @throws {AIStudioSubscriptionRequired} When subscription is not active.
+     */
+    async aiSearch(prompt, params = {}) {
+        return this._aiApiPost(config_1.APIRoutes.AISearch, { prompt, ...params });
+    }
+    /**
+     * AI-guided browser automation using natural language commands.
+     * Requires an active AI Studio subscription.
+     * @param {string} url - The URL to automate.
+     * @param {string} prompt - Natural language description of browser actions.
+     * @param {AIRequestParams} [params={}] - Additional parameters for automation.
+     * @returns {Promise<any>} The automation results.
+     * @throws {AIStudioSubscriptionRequired} When subscription is not active.
+     */
+    async aiBrowser(url, prompt, params = {}) {
+        return this._aiApiPost(config_1.APIRoutes.AIBrowser, { url, prompt, ...params });
+    }
+    /**
+     * AI-guided link extraction and filtering.
+     * Requires an active AI Studio subscription.
+     * @param {string} url - The URL to extract links from.
+     * @param {string} prompt - Natural language description of what links to find.
+     * @param {AIRequestParams} [params={}] - Additional parameters.
+     * @returns {Promise<any>} The filtered links based on AI analysis.
+     * @throws {AIStudioSubscriptionRequired} When subscription is not active.
+     */
+    async aiLinks(url, prompt, params = {}) {
+        return this._aiApiPost(config_1.APIRoutes.AILinks, { url, prompt, ...params });
+    }
     /**
      * Handles errors from API requests.
      * @param {Response} response - The fetch response object.

package/dist/config.d.ts

@@ -591,12 +591,88 @@ export declare enum ApiVersion {
 }
 export declare enum APIRoutes {
     Crawl = "crawl",
+    Scrape = "scrape",
+    Unblocker = "unblocker",
     Links = "links",
     Screenshot = "screenshot",
     Search = "search",
     Transform = "transform",
     Data = "data",
-    DataCredits = "data/credits"
+    DataCredits = "data/credits",
+    AICrawl = "ai/crawl",
+    AIScrape = "ai/scrape",
+    AISearch = "ai/search",
+    AIBrowser = "ai/browser",
+    AILinks = "ai/links"
+}
+/**
+ * AI Studio subscription tiers with their rate limits (requests per second).
+ */
+export declare const AI_STUDIO_RATE_LIMITS: {
+    readonly starter: 1;
+    readonly lite: 5;
+    readonly standard: 10;
+    readonly custom: 25;
+};
+export type AIStudioTier = keyof typeof AI_STUDIO_RATE_LIMITS;
+/**
+ * Parameters for AI Studio endpoints.
+ * All AI endpoints require a 'prompt' parameter for natural language instructions.
+ */
+export interface AIRequestParams extends Omit<SpiderParams, "url"> {
+    /** Natural language instruction for AI-guided extraction */
+    prompt: string;
+}
+/**
+ * AI Studio subscription info and URLs.
+ */
+export declare const AIStudioInfo: {
+    /** Base URL for AI Studio */
+    readonly baseUrl: "https://aistudio.spider.cloud";
+    /** URL for pricing/subscription page */
+    readonly pricingUrl: "https://aistudio.spider.cloud/pricing";
+    /** URL for AI Studio documentation */
+    readonly docsUrl: "https://aistudio.spider.cloud/docs";
+    /** Available subscription tiers */
+    readonly tiers: {
+        readonly starter: {
+            readonly price: 6;
+            readonly credits: 30000;
+            readonly rateLimit: 1;
+        };
+        readonly lite: {
+            readonly price: 30;
+            readonly credits: 150000;
+            readonly rateLimit: 5;
+        };
+        readonly standard: {
+            readonly price: 125;
+            readonly credits: 600000;
+            readonly rateLimit: 10;
+        };
+        readonly custom: {
+            readonly price: 600;
+            readonly credits: 3000000;
+            readonly rateLimit: 25;
+        };
+    };
+};
+/**
+ * Error thrown when AI Studio subscription is required but not active.
+ */
+export declare class AIStudioSubscriptionRequired extends Error {
+    /** URL to subscribe to AI Studio */
+    subscribeUrl: string;
+    constructor(message?: string);
+}
+/**
+ * Error thrown when AI Studio rate limit is exceeded.
+ */
+export declare class AIStudioRateLimitExceeded extends Error {
+    retryAfterMs: number;
+    /** URL to upgrade subscription for higher rate limits */
+    upgradeUrl: string;
+    constructor(retryAfterMs: number, currentTier?: AIStudioTier);
 }
 export declare const APISchema: {
     url: string;

package/dist/config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setBaseUrl = exports.APISchema = exports.APIRoutes = exports.ApiVersion = exports.Collection = exports.RedirectPolicy = void 0;
+exports.setBaseUrl = exports.APISchema = exports.AIStudioRateLimitExceeded = exports.AIStudioSubscriptionRequired = exports.AIStudioInfo = exports.AI_STUDIO_RATE_LIMITS = exports.APIRoutes = exports.ApiVersion = exports.Collection = exports.RedirectPolicy = void 0;
 // The HTTP redirect policy to use. Loose allows all domains and Strict only allows relative requests to the domain.
 var RedirectPolicy;
 (function (RedirectPolicy) {
@@ -32,6 +32,10 @@ var APIRoutes;
 (function (APIRoutes) {
     // Crawl a website to collect the contents. Can be one page or many.
     APIRoutes["Crawl"] = "crawl";
+    // Scrape a website to collect the contents. Can be one page or many.
+    APIRoutes["Scrape"] = "scrape";
+    // Unblock a website to collect the contents. Can be one page or many.
+    APIRoutes["Unblocker"] = "unblocker";
     // Crawl a website to collect the links. Can be one page or many.
     APIRoutes["Links"] = "links";
     // Crawl a website to collect screenshots. Can be one page or many.
@@ -44,7 +48,66 @@ var APIRoutes;
     APIRoutes["Data"] = "data";
     // Get the credits remaining for an account.
     APIRoutes["DataCredits"] = "data/credits";
+    // AI Studio endpoints (requires AI Studio subscription)
+    APIRoutes["AICrawl"] = "ai/crawl";
+    APIRoutes["AIScrape"] = "ai/scrape";
+    APIRoutes["AISearch"] = "ai/search";
+    APIRoutes["AIBrowser"] = "ai/browser";
+    APIRoutes["AILinks"] = "ai/links";
 })(APIRoutes || (exports.APIRoutes = APIRoutes = {}));
+/**
+ * AI Studio subscription tiers with their rate limits (requests per second).
+ */
+exports.AI_STUDIO_RATE_LIMITS = {
+    starter: 1,
+    lite: 5,
+    standard: 10,
+    custom: 25,
+};
+/**
+ * AI Studio subscription info and URLs.
+ */
+exports.AIStudioInfo = {
+    /** Base URL for AI Studio */
+    baseUrl: "https://aistudio.spider.cloud",
+    /** URL for pricing/subscription page */
+    pricingUrl: "https://aistudio.spider.cloud/pricing",
+    /** URL for AI Studio documentation */
+    docsUrl: "https://aistudio.spider.cloud/docs",
+    /** Available subscription tiers */
+    tiers: {
+        starter: { price: 6, credits: 30000, rateLimit: 1 },
+        lite: { price: 30, credits: 150000, rateLimit: 5 },
+        standard: { price: 125, credits: 600000, rateLimit: 10 },
+        custom: { price: 600, credits: 3000000, rateLimit: 25 },
+    },
+};
+/**
+ * Error thrown when AI Studio subscription is required but not active.
+ */
+class AIStudioSubscriptionRequired extends Error {
+    constructor(message = "AI Studio subscription required to use /ai/* endpoints.") {
+        super(`${message}\n\nSubscribe at: ${exports.AIStudioInfo.pricingUrl}\n\nPlans start at $${exports.AIStudioInfo.tiers.starter.price}/month with ${exports.AIStudioInfo.tiers.starter.credits.toLocaleString()} credits.`);
+        this.name = "AIStudioSubscriptionRequired";
+        this.subscribeUrl = exports.AIStudioInfo.pricingUrl;
+    }
+}
+exports.AIStudioSubscriptionRequired = AIStudioSubscriptionRequired;
+/**
+ * Error thrown when AI Studio rate limit is exceeded.
+ */
+class AIStudioRateLimitExceeded extends Error {
+    constructor(retryAfterMs, currentTier) {
+        const upgradeHint = currentTier && currentTier !== "custom"
+            ? `\n\nUpgrade your plan for higher rate limits: ${exports.AIStudioInfo.pricingUrl}`
+            : "";
+        super(`AI Studio rate limit exceeded. Retry after ${retryAfterMs}ms.${upgradeHint}`);
+        this.name = "AIStudioRateLimitExceeded";
+        this.retryAfterMs = retryAfterMs;
+        this.upgradeUrl = exports.AIStudioInfo.pricingUrl;
+    }
+}
+exports.AIStudioRateLimitExceeded = AIStudioRateLimitExceeded;
 // The base API target info for Spider Cloud.
 exports.APISchema = {
     url: "https://api.spider.cloud",

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { Spider } from "./client";
-export { Collection, setBaseUrl, APISchema } from "./config";
-export type { SpiderParams, Budget, Viewport, QueryRequest } from "./config";
+export { Collection, setBaseUrl, APISchema, AI_STUDIO_RATE_LIMITS, AIStudioInfo, AIStudioSubscriptionRequired, AIStudioRateLimitExceeded, } from "./config";
+export type { SpiderParams, Budget, Viewport, QueryRequest, AIRequestParams, AIStudioTier, } from "./config";

package/dist/index.js

@@ -1,9 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.APISchema = exports.setBaseUrl = exports.Collection = exports.Spider = void 0;
+exports.AIStudioRateLimitExceeded = exports.AIStudioSubscriptionRequired = exports.AIStudioInfo = exports.AI_STUDIO_RATE_LIMITS = exports.APISchema = exports.setBaseUrl = exports.Collection = exports.Spider = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "Spider", { enumerable: true, get: function () { return client_1.Spider; } });
 var config_1 = require("./config");
 Object.defineProperty(exports, "Collection", { enumerable: true, get: function () { return config_1.Collection; } });
 Object.defineProperty(exports, "setBaseUrl", { enumerable: true, get: function () { return config_1.setBaseUrl; } });
 Object.defineProperty(exports, "APISchema", { enumerable: true, get: function () { return config_1.APISchema; } });
+Object.defineProperty(exports, "AI_STUDIO_RATE_LIMITS", { enumerable: true, get: function () { return config_1.AI_STUDIO_RATE_LIMITS; } });
+Object.defineProperty(exports, "AIStudioInfo", { enumerable: true, get: function () { return config_1.AIStudioInfo; } });
+Object.defineProperty(exports, "AIStudioSubscriptionRequired", { enumerable: true, get: function () { return config_1.AIStudioSubscriptionRequired; } });
+Object.defineProperty(exports, "AIStudioRateLimitExceeded", { enumerable: true, get: function () { return config_1.AIStudioRateLimitExceeded; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spider-cloud/spider-client",
-  "version": "0.1.84",
+  "version": "0.1.87",
   "description": "Isomorphic Javascript SDK for Spider Cloud services",
   "scripts": {
     "test": "node --import tsx  --test __tests__/*test.ts",