oilpriceapi 0.7.0 → 0.8.2

package/README.md

@@ -1,9 +1,15 @@
 # Oil Price API - Node.js SDK
 
+> **Real-time oil and commodity price data for Node.js** - Professional-grade API at 98% less cost than Bloomberg Terminal
+
 [![npm version](https://badge.fury.io/js/oilpriceapi.svg)](https://www.npmjs.com/package/oilpriceapi)
+[![npm downloads](https://img.shields.io/npm/dm/oilpriceapi)](https://www.npmjs.com/package/oilpriceapi)
+[![Tests](https://github.com/OilpriceAPI/oilpriceapi-node/actions/workflows/test.yml/badge.svg)](https://github.com/OilpriceAPI/oilpriceapi-node/actions/workflows/test.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Official Node.js SDK for [Oil Price API](https://www.oilpriceapi.com) - Get real-time and historical oil & commodity prices.
+**[Get Free API Key](https://www.oilpriceapi.com/signup?utm_source=npm&utm_medium=sdk&utm_campaign=readme)** | **[Documentation](https://docs.oilpriceapi.com)** | **[Pricing](https://www.oilpriceapi.com/pricing?utm_source=npm&utm_medium=sdk&utm_campaign=pricing)**
+
+The official Node.js/TypeScript SDK for [OilPriceAPI](https://www.oilpriceapi.com) - Real-time and historical oil prices for Brent Crude, WTI, Natural Gas, and 100+ commodities.
 
 ## Features
 
@@ -33,7 +39,7 @@ import { OilPriceAPI } from "oilpriceapi";
 
 // Initialize the client
 const client = new OilPriceAPI({
-  apiKey: "your_api_key_here", // Get your free key at https://www.oilpriceapi.com
+  apiKey: "your_api_key_here", // Get your free key at https://www.oilpriceapi.com/signup
   retries: 3, // Automatic retries (default: 3)
   timeout: 30000, // Request timeout in ms (default: 30000)
 });
@@ -706,7 +712,7 @@ new OilPriceAPI(config: OilPriceAPIConfig)
 
 **Parameters:**
 
-- `config.apiKey` (string, required) - Your API key from https://www.oilpriceapi.com
+- `config.apiKey` (string, required) - Your API key from https://www.oilpriceapi.com/signup
 - `config.baseUrl` (string, optional) - Custom API base URL (for testing)
 
 #### Methods
@@ -928,7 +934,7 @@ See the [full list of 79 commodities](https://www.oilpriceapi.com/commodities) i
 - **Business**: 200,000 requests/month - $199/mo
 - **Enterprise**: Custom limits - Contact us
 
-Get started with a free API key at [oilpriceapi.com](https://www.oilpriceapi.com).
+Get started with a free API key at [oilpriceapi.com/signup](https://www.oilpriceapi.com/signup?utm_source=npm&utm_medium=sdk&utm_campaign=readme).
 
 ## Requirements
 
@@ -950,10 +956,9 @@ We welcome contributions! Please see our [Contributing Guide](https://github.com
 
 ## Support
 
-- 📧 Email: support@oilpriceapi.com
-- 🐛 Issues: [GitHub Issues](https://github.com/OilpriceAPI/oilpriceapi-node/issues)
-- 📚 Documentation: [oilpriceapi.com/docs](https://www.oilpriceapi.com/docs)
-- 💬 Discord: [Join our community](https://discord.gg/oilpriceapi)
+- Email: support@oilpriceapi.com
+- Issues: [GitHub Issues](https://github.com/OilpriceAPI/oilpriceapi-node/issues)
+- Docs: [Documentation](https://docs.oilpriceapi.com)
 
 ## License
 
@@ -961,11 +966,38 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ## Links
 
-- [Website](https://www.oilpriceapi.com)
-- [API Documentation](https://www.oilpriceapi.com/docs)
+- [OilPriceAPI Website](https://www.oilpriceapi.com)
+- [API Documentation](https://docs.oilpriceapi.com)
+- [Pricing](https://www.oilpriceapi.com/pricing?utm_source=npm&utm_medium=sdk&utm_campaign=pricing)
+- [Status Page](https://status.oilpriceapi.com)
 - [GitHub Repository](https://github.com/OilpriceAPI/oilpriceapi-node)
 - [npm Package](https://www.npmjs.com/package/oilpriceapi)
 
 ---
 
-Made with ❤️ by the Oil Price API team
+## Why OilPriceAPI?
+
+[OilPriceAPI](https://www.oilpriceapi.com) provides professional-grade commodity price data at **98% less cost than Bloomberg Terminal** ($24,000/year vs $45/month). Trusted by energy traders, financial analysts, and developers worldwide.
+
+### Key Benefits
+
+- **Real-time data** updated every 5 minutes
+- **Historical data** for trend analysis and backtesting
+- **99.9% uptime** with enterprise-grade reliability
+- **5-minute integration** with this Node.js SDK
+- **Free tier** with 100 requests to get started
+
+**[Start Free](https://www.oilpriceapi.com/signup?utm_source=npm&utm_medium=sdk&utm_campaign=readme)** | **[View Pricing](https://www.oilpriceapi.com/pricing?utm_source=npm&utm_medium=sdk&utm_campaign=pricing)** | **[Read Docs](https://docs.oilpriceapi.com)**
+
+---
+
+## Also Available As
+
+- **[Python SDK](https://pypi.org/project/oilpriceapi/)** - Python client with Pandas integration
+- **[Go SDK](https://github.com/OilpriceAPI/oilpriceapi-go)** - Idiomatic Go client
+- **[MCP Server](https://www.npmjs.com/package/oilpriceapi-mcp)** - Model Context Protocol server for Claude, Cursor, and VS Code
+- **[Google Sheets Add-on](https://github.com/OilpriceAPI/google-sheets-addin)** - Custom functions for spreadsheets
+
+---
+
+Made with care by the OilPriceAPI Team

package/dist/cjs/client.js

@@ -0,0 +1,490 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OilPriceAPI = void 0;
+const errors_js_1 = require("./errors.js");
+const diesel_js_1 = require("./resources/diesel.js");
+const alerts_js_1 = require("./resources/alerts.js");
+const commodities_js_1 = require("./resources/commodities.js");
+const futures_js_1 = require("./resources/futures.js");
+const storage_js_1 = require("./resources/storage.js");
+const rig_counts_js_1 = require("./resources/rig-counts.js");
+const bunker_fuels_js_1 = require("./resources/bunker-fuels.js");
+const analytics_js_1 = require("./resources/analytics.js");
+const forecasts_js_1 = require("./resources/forecasts.js");
+const data_quality_js_1 = require("./resources/data-quality.js");
+const drilling_js_1 = require("./resources/drilling.js");
+const index_js_1 = require("./resources/ei/index.js");
+const webhooks_js_1 = require("./resources/webhooks.js");
+const data_sources_js_1 = require("./resources/data-sources.js");
+const version_js_1 = require("./version.js");
+/**
+ * Official Node.js client for Oil Price API
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({
+ *   apiKey: 'your_api_key_here',
+ *   retries: 3,
+ *   timeout: 30000
+ * });
+ *
+ * // Get latest prices
+ * const prices = await client.getLatestPrices();
+ *
+ * // Get WTI price only
+ * const wti = await client.getLatestPrices({ commodity: 'WTI_USD' });
+ *
+ * // Get historical data
+ * const historical = await client.getHistoricalPrices({
+ *   period: 'past_week',
+ *   commodity: 'BRENT_CRUDE_USD'
+ * });
+ * ```
+ */
+class OilPriceAPI {
+    constructor(config = {}) {
+        this.apiKey = config.apiKey || process.env.OILPRICEAPI_KEY || "";
+        if (!this.apiKey) {
+            throw new errors_js_1.OilPriceAPIError("API key required. Set OILPRICEAPI_KEY env var or pass apiKey in config.");
+        }
+        this.baseUrl = config.baseUrl || "https://api.oilpriceapi.com";
+        this.retries = config.retries !== undefined ? config.retries : 3;
+        this.retryDelay = config.retryDelay || 1000;
+        this.retryStrategy = config.retryStrategy || "exponential";
+        this.timeout = config.timeout || 90000; // 90 seconds for slow historical queries
+        this.debug = config.debug || false;
+        this.appUrl = config.appUrl;
+        this.appName = config.appName;
+        // Initialize resources
+        this.diesel = new diesel_js_1.DieselResource(this);
+        this.alerts = new alerts_js_1.AlertsResource(this);
+        this.commodities = new commodities_js_1.CommoditiesResource(this);
+        this.futures = new futures_js_1.FuturesResource(this);
+        this.storage = new storage_js_1.StorageResource(this);
+        this.rigCounts = new rig_counts_js_1.RigCountsResource(this);
+        this.bunkerFuels = new bunker_fuels_js_1.BunkerFuelsResource(this);
+        this.analytics = new analytics_js_1.AnalyticsResource(this);
+        this.forecasts = new forecasts_js_1.ForecastsResource(this);
+        this.dataQuality = new data_quality_js_1.DataQualityResource(this);
+        this.drilling = new drilling_js_1.DrillingIntelligenceResource(this);
+        this.ei = new index_js_1.EnergyIntelligenceResource(this);
+        this.webhooks = new webhooks_js_1.WebhooksResource(this);
+        this.dataSources = new data_sources_js_1.DataSourcesResource(this);
+    }
+    /**
+     * Log debug messages if debug mode is enabled
+     */
+    log(message, data) {
+        if (this.debug) {
+            const timestamp = new Date().toISOString();
+            console.log(`[OilPriceAPI ${timestamp}] ${message}`, data || "");
+        }
+    }
+    /**
+     * Calculate delay for retry based on strategy
+     */
+    calculateRetryDelay(attempt) {
+        switch (this.retryStrategy) {
+            case "exponential":
+                return this.retryDelay * Math.pow(2, attempt);
+            case "linear":
+                return this.retryDelay * (attempt + 1);
+            case "fixed":
+            default:
+                return this.retryDelay;
+        }
+    }
+    /**
+     * Sleep for specified milliseconds
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Determine if error is retryable
+     */
+    isRetryable(error) {
+        // Retry on network errors
+        if (error instanceof TypeError && error.message.includes("fetch")) {
+            return true;
+        }
+        // Retry on timeout errors
+        if (error instanceof errors_js_1.TimeoutError) {
+            return true;
+        }
+        // Retry on 5xx server errors
+        if (error instanceof errors_js_1.ServerError) {
+            return true;
+        }
+        // Retry on rate limit errors (with delay)
+        if (error instanceof errors_js_1.RateLimitError) {
+            return true;
+        }
+        // Don't retry on client errors (4xx except 429)
+        return false;
+    }
+    /**
+     * Internal method to make HTTP requests with retry and timeout.
+     * Supports all HTTP methods (GET, POST, PATCH, DELETE) with consistent
+     * retry logic, timeout handling, and typed error responses.
+     */
+    async request(endpoint, params, options) {
+        // Build URL with query parameters
+        const url = new URL(`${this.baseUrl}${endpoint}`);
+        if (params) {
+            Object.entries(params).forEach(([key, value]) => {
+                if (value !== undefined && value !== null) {
+                    url.searchParams.append(key, value);
+                }
+            });
+        }
+        this.log(`Request: ${url.toString()}`);
+        let lastError = null;
+        // Retry loop
+        for (let attempt = 0; attempt <= this.retries; attempt++) {
+            try {
+                // Add retry info to logs
+                if (attempt > 0) {
+                    this.log(`Retry attempt ${attempt}/${this.retries}`);
+                }
+                // Create abort controller for timeout
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+                try {
+                    // Build headers with optional telemetry
+                    const headers = {
+                        Authorization: `Bearer ${this.apiKey}`,
+                        "Content-Type": "application/json",
+                        "User-Agent": (0, version_js_1.buildUserAgent)(),
+                        "X-SDK-Name": version_js_1.SDK_NAME,
+                        "X-SDK-Version": version_js_1.SDK_VERSION,
+                    };
+                    // Add optional telemetry headers (10% bonus for appUrl!)
+                    if (this.appUrl) {
+                        headers["X-App-URL"] = this.appUrl;
+                    }
+                    if (this.appName) {
+                        headers["X-App-Name"] = this.appName;
+                    }
+                    const fetchOptions = {
+                        method: options?.method || "GET",
+                        headers,
+                        signal: controller.signal,
+                    };
+                    if (options?.body !== undefined) {
+                        fetchOptions.body = JSON.stringify(options.body);
+                    }
+                    const response = await fetch(url.toString(), fetchOptions);
+                    clearTimeout(timeoutId);
+                    this.log(`Response: ${response.status} ${response.statusText}`);
+                    // Handle error responses
+                    if (!response.ok) {
+                        const errorBody = await response.text();
+                        let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+                        // Try to parse JSON error response
+                        try {
+                            const errorJson = JSON.parse(errorBody);
+                            errorMessage = errorJson.message || errorJson.error || errorMessage;
+                        }
+                        catch {
+                            // Use default error message if response isn't JSON
+                        }
+                        this.log(`Error response: ${errorMessage}`);
+                        // Throw specific error types based on status code
+                        switch (response.status) {
+                            case 401:
+                                throw new errors_js_1.AuthenticationError(errorMessage);
+                            case 404:
+                                throw new errors_js_1.NotFoundError(errorMessage);
+                            case 429:
+                                const retryAfter = response.headers.get("Retry-After");
+                                const rateLimitError = new errors_js_1.RateLimitError(errorMessage, retryAfter ? parseInt(retryAfter, 10) : undefined);
+                                // If rate limited and we have retries left, wait and retry
+                                if (attempt < this.retries && rateLimitError.retryAfter) {
+                                    this.log(`Rate limited. Waiting ${rateLimitError.retryAfter}s`);
+                                    await this.sleep(rateLimitError.retryAfter * 1000);
+                                    continue;
+                                }
+                                throw rateLimitError;
+                            case 500:
+                            case 502:
+                            case 503:
+                            case 504:
+                                throw new errors_js_1.ServerError(errorMessage, response.status);
+                            default:
+                                throw new errors_js_1.OilPriceAPIError(errorMessage, response.status, "HTTP_ERROR");
+                        }
+                    }
+                    // Handle empty responses (e.g., 204 No Content from DELETE)
+                    const responseText = await response.text();
+                    if (!responseText) {
+                        this.log("Empty response body");
+                        return {};
+                    }
+                    // Parse successful response
+                    const responseData = JSON.parse(responseText);
+                    this.log("Response data received", {
+                        status: responseData.status,
+                        hasData: !!responseData.data,
+                    });
+                    // Handle different response structures
+                    // Latest endpoint: { status, data: { price, ... } }
+                    // Historical endpoint: { status, data: { prices: [...] } }
+                    if (responseData.status === "success" && responseData.data) {
+                        if (responseData.data.prices) {
+                            // Historical endpoint - return prices array
+                            this.log(`Returning ${responseData.data.prices.length} prices`);
+                            return responseData.data.prices;
+                        }
+                        else if (responseData.data.price !== undefined) {
+                            // Latest endpoint - wrap single price in array
+                            this.log("Returning single price (wrapped in array)");
+                            return [responseData.data];
+                        }
+                    }
+                    // Fallback - return data as-is (used by resource mutations, alerts, webhooks, etc.)
+                    this.log("Returning data as-is");
+                    return (responseData.data !== undefined ? responseData.data : responseData);
+                }
+                catch (error) {
+                    // Handle abort (timeout)
+                    if (error instanceof Error && error.name === "AbortError") {
+                        throw new errors_js_1.TimeoutError("Request timeout", this.timeout);
+                    }
+                    throw error;
+                }
+            }
+            catch (error) {
+                lastError = error;
+                this.log(`Request failed: ${lastError.message}`, {
+                    attempt,
+                    retryable: this.isRetryable(lastError),
+                });
+                // Re-throw our custom errors if not retryable
+                if (error instanceof errors_js_1.OilPriceAPIError && !this.isRetryable(error)) {
+                    throw error;
+                }
+                // If this was our last attempt, throw the error
+                if (attempt === this.retries) {
+                    if (error instanceof errors_js_1.OilPriceAPIError) {
+                        throw error;
+                    }
+                    // Wrap fetch errors (network issues, etc.)
+                    if (error instanceof Error) {
+                        throw new errors_js_1.OilPriceAPIError(`Request failed after ${this.retries + 1} attempts: ${error.message}`, undefined, "NETWORK_ERROR");
+                    }
+                    throw error;
+                }
+                // Calculate delay and retry
+                const delay = this.calculateRetryDelay(attempt);
+                this.log(`Waiting ${delay}ms before retry...`);
+                await this.sleep(delay);
+            }
+        }
+        // This should never be reached, but TypeScript wants it
+        throw lastError || new errors_js_1.OilPriceAPIError("Unknown error occurred");
+    }
+    /**
+     * Get the latest prices for all commodities or a specific commodity
+     *
+     * @param options - Optional filters
+     * @returns Array of price objects
+     *
+     * @example
+     * ```typescript
+     * // Get all latest prices
+     * const allPrices = await client.getLatestPrices();
+     *
+     * // Get WTI price only
+     * const wti = await client.getLatestPrices({ commodity: 'WTI_USD' });
+     * ```
+     */
+    async getLatestPrices(options) {
+        const params = {};
+        if (options?.commodity) {
+            params.by_code = options.commodity;
+        }
+        return this.request("/v1/prices/latest", params);
+    }
+    /**
+     * Get historical prices for a time period
+     *
+     * @param options - Time period and filter options
+     * @returns Array of historical price objects
+     *
+     * @example
+     * ```typescript
+     * // Get past week of WTI prices
+     * const weekPrices = await client.getHistoricalPrices({
+     *   period: 'past_week',
+     *   commodity: 'WTI_USD'
+     * });
+     *
+     * // Get custom date range
+     * const customPrices = await client.getHistoricalPrices({
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31',
+     *   commodity: 'BRENT_CRUDE_USD'
+     * });
+     * ```
+     */
+    async getHistoricalPrices(options) {
+        const params = {};
+        if (options?.period) {
+            params.period = options.period;
+        }
+        if (options?.commodity) {
+            params.by_code = options.commodity;
+        }
+        if (options?.startDate) {
+            params.start_date = options.startDate;
+        }
+        if (options?.endDate) {
+            params.end_date = options.endDate;
+        }
+        // PERFORMANCE FIX (December 24, 2025):
+        // Pass interval parameter to enable aggregated queries
+        // This reduces response times from 74s to <1s for year-long queries
+        // by returning 365 daily points instead of 600k+ raw points
+        if (options?.interval) {
+            params.interval = options.interval;
+        }
+        // Pagination parameters
+        if (options?.perPage !== undefined) {
+            params.per_page = options.perPage.toString();
+        }
+        if (options?.page !== undefined) {
+            params.page = options.page.toString();
+        }
+        // CRITICAL FIX (December 17, 2025):
+        // Use /v1/prices/past_year endpoint instead of /v1/prices
+        // The /v1/prices endpoint does NOT correctly handle start_date/end_date parameters
+        // This was the same bug that affected the Python SDK (fixed in v1.4.4)
+        // Issue: SDK was returning wrong dates for historical queries
+        // Root Cause: Backend has_scope :by_period not working on /v1/prices
+        // Solution: Use /v1/prices/past_year which uses direct WHERE clauses
+        return this.request("/v1/prices/past_year", params);
+    }
+    /**
+     * Paginate through historical prices automatically.
+     *
+     * Returns an async generator that yields pages of prices, fetching
+     * the next page only when needed. Avoids loading all data into memory.
+     *
+     * @param options - Same options as getHistoricalPrices, plus perPage (default: 100)
+     *
+     * @example
+     * ```typescript
+     * // Iterate through all pages
+     * for await (const page of client.paginateHistoricalPrices({
+     *   commodity: 'BRENT_CRUDE_USD',
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31',
+     *   perPage: 100,
+     * })) {
+     *   console.log(`Got ${page.length} prices`);
+     *   // Process each page...
+     * }
+     *
+     * // Or collect all prices
+     * const allPrices: Price[] = [];
+     * for await (const page of client.paginateHistoricalPrices({ commodity: 'WTI_USD' })) {
+     *   allPrices.push(...page);
+     * }
+     * ```
+     */
+    async *paginateHistoricalPrices(options) {
+        const perPage = options?.perPage || 100;
+        let page = 1;
+        while (true) {
+            const results = await this.getHistoricalPrices({
+                ...options,
+                page,
+                perPage,
+            });
+            if (results.length === 0)
+                break;
+            yield results;
+            if (results.length < perPage)
+                break;
+            page++;
+        }
+    }
+    /**
+     * Get prices from your connected data sources (BYOS)
+     *
+     * Requires Data Connector feature enabled on your organization.
+     *
+     * @example
+     * ```typescript
+     * // Get all connected prices
+     * const prices = await client.getDataConnectorPrices();
+     *
+     * // Filter by fuel type
+     * const vlsfo = await client.getDataConnectorPrices({ fuelType: 'VLSFO' });
+     *
+     * // Filter by port
+     * const singapore = await client.getDataConnectorPrices({ port: 'SINGAPORE' });
+     * ```
+     */
+    async getDataConnectorPrices(options = {}) {
+        const params = {};
+        if (options.fuelType)
+            params.fuel_type = options.fuelType;
+        if (options.port)
+            params.port = options.port;
+        if (options.region)
+            params.region = options.region;
+        if (options.since)
+            params.since = options.since;
+        const response = await this.request("/v1/prices/data-connector", params);
+        return response.prices;
+    }
+    /**
+     * Get metadata for all supported commodities
+     *
+     * @returns Object containing array of commodities
+     *
+     * @example
+     * ```typescript
+     * const response = await client.getCommodities();
+     * console.log(response.commodities); // Array of commodity objects
+     * ```
+     */
+    async getCommodities() {
+        return this.request("/v1/commodities", {});
+    }
+    /**
+     * Get all commodity categories with their commodities
+     *
+     * @returns Object with category keys mapped to category objects
+     *
+     * @example
+     * ```typescript
+     * const categories = await client.getCommodityCategories();
+     * console.log(categories.oil.name); // "Oil"
+     * console.log(categories.oil.commodities.length); // 11
+     * ```
+     */
+    async getCommodityCategories() {
+        return this.request("/v1/commodities/categories", {});
+    }
+    /**
+     * Get metadata for a specific commodity by code
+     *
+     * @param code - Commodity code (e.g., "WTI_USD", "BRENT_CRUDE_USD")
+     * @returns Commodity metadata object
+     *
+     * @example
+     * ```typescript
+     * const commodity = await client.getCommodity('WTI_USD');
+     * console.log(commodity.name); // "WTI Crude Oil"
+     * ```
+     */
+    async getCommodity(code) {
+        return this.request(`/v1/commodities/${code}`, {});
+    }
+}
+exports.OilPriceAPI = OilPriceAPI;

package/dist/cjs/errors.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutError = exports.ValidationError = exports.ServerError = exports.NotFoundError = exports.RateLimitError = exports.AuthenticationError = exports.OilPriceAPIError = void 0;
+/**
+ * Base error class for all Oil Price API errors
+ */
+class OilPriceAPIError extends Error {
+    constructor(message, statusCode, code) {
+        super(message);
+        this.name = "OilPriceAPIError";
+        this.statusCode = statusCode;
+        this.code = code;
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+}
+exports.OilPriceAPIError = OilPriceAPIError;
+/**
+ * Thrown when API authentication fails (401)
+ */
+class AuthenticationError extends OilPriceAPIError {
+    constructor(message = "Invalid API key") {
+        super(message, 401, "AUTHENTICATION_ERROR");
+        this.name = "AuthenticationError";
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+/**
+ * Thrown when rate limit is exceeded (429)
+ */
+class RateLimitError extends OilPriceAPIError {
+    constructor(message = "Rate limit exceeded", retryAfter) {
+        super(message, 429, "RATE_LIMIT_ERROR");
+        this.name = "RateLimitError";
+        this.retryAfter = retryAfter;
+    }
+}
+exports.RateLimitError = RateLimitError;
+/**
+ * Thrown when requested resource is not found (404)
+ */
+class NotFoundError extends OilPriceAPIError {
+    constructor(message = "Resource not found") {
+        super(message, 404, "NOT_FOUND_ERROR");
+        this.name = "NotFoundError";
+    }
+}
+exports.NotFoundError = NotFoundError;
+/**
+ * Thrown when server returns 5xx error
+ */
+class ServerError extends OilPriceAPIError {
+    constructor(message = "Internal server error", statusCode = 500) {
+        super(message, statusCode, "SERVER_ERROR");
+        this.name = "ServerError";
+    }
+}
+exports.ServerError = ServerError;
+/**
+ * Thrown when SDK-side input validation fails
+ */
+class ValidationError extends OilPriceAPIError {
+    constructor(message) {
+        super(message, undefined, "VALIDATION_ERROR");
+        this.name = "ValidationError";
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Thrown when request exceeds timeout
+ */
+class TimeoutError extends OilPriceAPIError {
+    constructor(message = "Request timeout", timeout) {
+        super(`${message} (${timeout}ms)`, undefined, "TIMEOUT_ERROR");
+        this.name = "TimeoutError";
+    }
+}
+exports.TimeoutError = TimeoutError;