oilpriceapi 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Oil Price API
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,375 @@
+# Oil Price API - Node.js SDK
+
+[![npm version](https://badge.fury.io/js/oilpriceapi.svg)](https://www.npmjs.com/package/oilpriceapi)
+[![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.
+
+## Features
+
+- ✅ **Simple** - Get started in 5 lines of code
+- 🔒 **Type-Safe** - Full TypeScript support with detailed type definitions
+- ⚡ **Fast** - Zero dependencies, uses native fetch (Node 18+)
+- 🎯 **Comprehensive** - Covers all API endpoints
+- 🚀 **Modern** - ES Modules, async/await, Promise-based
+- 🛡️ **Robust** - Custom error classes for better error handling
+- 🔄 **Resilient** - Automatic retries with exponential backoff
+- ⏱️ **Reliable** - Request timeouts and smart error handling
+- 🐛 **Debuggable** - Built-in debug logging mode
+
+## Installation
+
+```bash
+npm install oilpriceapi
+```
+
+## Quick Start
+
+```typescript
+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
+  retries: 3,                    // Automatic retries (default: 3)
+  timeout: 30000                 // Request timeout in ms (default: 30000)
+});
+
+// Get latest prices
+const prices = await client.getLatestPrices();
+console.log(prices);
+```
+
+## Usage Examples
+
+### Get Latest Prices (All Commodities)
+
+```typescript
+const prices = await client.getLatestPrices();
+
+// Example output:
+// [
+//   {
+//     code: 'WTI_USD',
+//     name: 'WTI Crude Oil',
+//     value: 74.25,
+//     currency: 'USD',
+//     unit: 'barrel',
+//     timestamp: '2024-11-24T12:00:00Z',
+//     created_at: '2024-11-24T12:01:00Z',
+//     updated_at: '2024-11-24T12:01:00Z'
+//   },
+//   // ... more prices
+// ]
+```
+
+### Get Latest Price for Specific Commodity
+
+```typescript
+// Get only WTI crude oil price
+const wti = await client.getLatestPrices({ commodity: 'WTI_USD' });
+console.log(`WTI: $${wti[0].value} per barrel`);
+
+// Get only Brent crude price
+const brent = await client.getLatestPrices({ commodity: 'BRENT_CRUDE_USD' });
+console.log(`Brent: $${brent[0].value} per barrel`);
+```
+
+### Get Historical Prices (Past Week)
+
+```typescript
+const weekPrices = await client.getHistoricalPrices({
+  period: 'past_week',
+  commodity: 'WTI_USD'
+});
+
+console.log(`Got ${weekPrices.length} data points from the past week`);
+```
+
+### Get Historical Prices (Custom Date Range)
+
+```typescript
+const prices = await client.getHistoricalPrices({
+  startDate: '2024-01-01',
+  endDate: '2024-12-31',
+  commodity: 'BRENT_CRUDE_USD'
+});
+
+console.log(`Got ${prices.length} data points for 2024`);
+```
+
+### Advanced Configuration
+
+```typescript
+import { OilPriceAPI } from 'oilpriceapi';
+
+const client = new OilPriceAPI({
+  apiKey: 'your_key',
+
+  // Retry configuration
+  retries: 3,                    // Max retry attempts (default: 3)
+  retryDelay: 1000,              // Initial delay in ms (default: 1000)
+  retryStrategy: 'exponential',  // 'exponential', 'linear', or 'fixed'
+
+  // Timeout configuration
+  timeout: 30000,                // Request timeout in ms (default: 30000)
+
+  // Debug mode
+  debug: true                    // Enable debug logging (default: false)
+});
+```
+
+### Error Handling
+
+```typescript
+import {
+  OilPriceAPI,
+  AuthenticationError,
+  RateLimitError,
+  NotFoundError,
+  TimeoutError,
+  ServerError
+} from 'oilpriceapi';
+
+const client = new OilPriceAPI({ apiKey: 'your_key' });
+
+try {
+  const prices = await client.getLatestPrices();
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key:', error.message);
+  } else if (error instanceof RateLimitError) {
+    console.error('Rate limit exceeded. Retry after:', error.retryAfter, 'seconds');
+  } else if (error instanceof TimeoutError) {
+    console.error('Request timed out:', error.message);
+  } else if (error instanceof ServerError) {
+    console.error('Server error:', error.statusCode, error.message);
+  } else if (error instanceof NotFoundError) {
+    console.error('Commodity not found:', error.message);
+  } else {
+    console.error('Unknown error:', error);
+  }
+}
+```
+
+### Debug Mode
+
+Enable debug logging to see detailed request/response information:
+
+```typescript
+const client = new OilPriceAPI({
+  apiKey: 'your_key',
+  debug: true
+});
+
+// This will log all requests, responses, retries, and errors
+const prices = await client.getLatestPrices();
+
+// Example output:
+// [OilPriceAPI 2024-11-24T20:28:23.145Z] Request: https://api.oilpriceapi.com/v1/prices/latest
+// [OilPriceAPI 2024-11-24T20:28:23.393Z] Response: 200 OK
+// [OilPriceAPI 2024-11-24T20:28:23.394Z] Response data received { status: 'success', hasData: true }
+```
+
+## Integration Examples
+
+### Express.js
+
+```typescript
+import express from 'express';
+import { OilPriceAPI } from 'oilpriceapi';
+
+const app = express();
+const oilPrices = new OilPriceAPI({
+  apiKey: process.env.OIL_PRICE_API_KEY
+});
+
+app.get('/api/prices', async (req, res) => {
+  try {
+    const prices = await oilPrices.getLatestPrices();
+    res.json({ success: true, data: prices });
+  } catch (error) {
+    res.status(500).json({
+      success: false,
+      error: error.message
+    });
+  }
+});
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+### Next.js API Route
+
+```typescript
+// app/api/prices/route.ts
+import { OilPriceAPI } from 'oilpriceapi';
+
+const client = new OilPriceAPI({
+  apiKey: process.env.OIL_PRICE_API_KEY
+});
+
+export async function GET() {
+  try {
+    const prices = await client.getLatestPrices();
+    return Response.json(prices);
+  } catch (error) {
+    return Response.json(
+      { error: error.message },
+      { status: 500 }
+    );
+  }
+}
+```
+
+### Price Monitoring Script
+
+```typescript
+import { OilPriceAPI } from 'oilpriceapi';
+
+const client = new OilPriceAPI({ apiKey: process.env.OIL_PRICE_API_KEY });
+
+async function checkPrice() {
+  const wti = await client.getLatestPrices({ commodity: 'WTI_USD' });
+  const price = wti[0].value;
+
+  console.log(`Current WTI price: $${price}`);
+
+  if (price < 70) {
+    console.log('🚨 ALERT: WTI below $70!');
+    // Send notification, email, etc.
+  }
+}
+
+// Check every 5 minutes
+setInterval(checkPrice, 5 * 60 * 1000);
+checkPrice(); // Run immediately
+```
+
+## API Reference
+
+### `OilPriceAPI`
+
+Main client class for interacting with the Oil Price API.
+
+#### Constructor
+
+```typescript
+new OilPriceAPI(config: OilPriceAPIConfig)
+```
+
+**Parameters:**
+- `config.apiKey` (string, required) - Your API key from https://www.oilpriceapi.com
+- `config.baseUrl` (string, optional) - Custom API base URL (for testing)
+
+#### Methods
+
+##### `getLatestPrices(options?)`
+
+Get the latest prices for all commodities or a specific commodity.
+
+**Parameters:**
+- `options.commodity` (string, optional) - Filter by commodity code (e.g., "WTI_USD")
+
+**Returns:** `Promise<Price[]>`
+
+##### `getHistoricalPrices(options?)`
+
+Get historical prices for a time period.
+
+**Parameters:**
+- `options.period` (string, optional) - One of: "past_week", "past_month", "past_year"
+- `options.commodity` (string, optional) - Filter by commodity code
+- `options.startDate` (string, optional) - Start date in ISO 8601 format (YYYY-MM-DD)
+- `options.endDate` (string, optional) - End date in ISO 8601 format (YYYY-MM-DD)
+
+**Returns:** `Promise<Price[]>`
+
+### Types
+
+#### `Price`
+
+```typescript
+interface Price {
+  code: string;          // Commodity code (e.g., "WTI_USD")
+  name: string;          // Human-readable name
+  value: number;         // Price value
+  currency: string;      // Currency code (e.g., "USD")
+  unit: string;          // Unit of measurement (e.g., "barrel")
+  timestamp: string;     // ISO 8601 timestamp
+  created_at: string;    // ISO 8601 timestamp
+  updated_at: string;    // ISO 8601 timestamp
+}
+```
+
+### Error Classes
+
+All errors extend `OilPriceAPIError`:
+
+- `AuthenticationError` (401) - Invalid API key
+- `RateLimitError` (429) - Rate limit exceeded
+- `NotFoundError` (404) - Resource not found
+- `ServerError` (5xx) - Server-side error
+
+## Available Commodities
+
+The API provides prices for the following commodities:
+
+- **Crude Oil**: WTI, Brent Crude
+- **Refined Products**: Gasoline, Diesel, Heating Oil, Jet Fuel
+- **Natural Gas**: US Natural Gas, EU Natural Gas, UK Natural Gas
+- **And more...**
+
+See the [full list of commodities](https://www.oilpriceapi.com/commodities) in the documentation.
+
+## Pricing & Rate Limits
+
+- **Free Tier**: 1,000 requests/month
+- **Starter**: 50,000 requests/month - $49/mo
+- **Professional**: 100,000 requests/month - $99/mo
+- **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).
+
+## Requirements
+
+- Node.js 18.0.0 or higher (for native fetch support)
+- TypeScript 5.0+ (if using TypeScript)
+
+## TypeScript Support
+
+This package is written in TypeScript and includes full type definitions. You get:
+
+- ✅ Full autocomplete in your IDE
+- ✅ Type checking for method parameters
+- ✅ Detailed JSDoc comments
+- ✅ Type-safe error handling
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](https://github.com/OilpriceAPI/oilpriceapi-node/blob/main/CONTRIBUTING.md) for details.
+
+## 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)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Links
+
+- [Website](https://www.oilpriceapi.com)
+- [API Documentation](https://www.oilpriceapi.com/docs)
+- [GitHub Repository](https://github.com/OilpriceAPI/oilpriceapi-node)
+- [npm Package](https://www.npmjs.com/package/oilpriceapi)
+
+---
+
+Made with ❤️ by the Oil Price API team

package/dist/client.d.ts

@@ -0,0 +1,96 @@
+import type { OilPriceAPIConfig, Price, LatestPricesOptions, HistoricalPricesOptions } from './types.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'
+ * });
+ * ```
+ */
+export declare class OilPriceAPI {
+    private apiKey;
+    private baseUrl;
+    private retries;
+    private retryDelay;
+    private retryStrategy;
+    private timeout;
+    private debug;
+    constructor(config: OilPriceAPIConfig);
+    /**
+     * Log debug messages if debug mode is enabled
+     */
+    private log;
+    /**
+     * Calculate delay for retry based on strategy
+     */
+    private calculateRetryDelay;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+    /**
+     * Determine if error is retryable
+     */
+    private isRetryable;
+    /**
+     * Internal method to make HTTP requests with retry and timeout
+     */
+    private request;
+    /**
+     * 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' });
+     * ```
+     */
+    getLatestPrices(options?: LatestPricesOptions): Promise<Price[]>;
+    /**
+     * 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'
+     * });
+     * ```
+     */
+    getHistoricalPrices(options?: HistoricalPricesOptions): Promise<Price[]>;
+}

package/dist/client.js

@@ -0,0 +1,291 @@
+import { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, TimeoutError, } from './errors.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'
+ * });
+ * ```
+ */
+export class OilPriceAPI {
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new OilPriceAPIError('API key is required');
+        }
+        this.apiKey = config.apiKey;
+        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 || 30000;
+        this.debug = config.debug || false;
+    }
+    /**
+     * 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 TimeoutError) {
+            return true;
+        }
+        // Retry on 5xx server errors
+        if (error instanceof ServerError) {
+            return true;
+        }
+        // Retry on rate limit errors (with delay)
+        if (error instanceof RateLimitError) {
+            return true;
+        }
+        // Don't retry on client errors (4xx except 429)
+        return false;
+    }
+    /**
+     * Internal method to make HTTP requests with retry and timeout
+     */
+    async request(endpoint, params) {
+        // 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 {
+                    const response = await fetch(url.toString(), {
+                        method: 'GET',
+                        headers: {
+                            'Authorization': `Bearer ${this.apiKey}`,
+                            'Content-Type': 'application/json',
+                            'User-Agent': 'oilpriceapi-node/0.2.0',
+                        },
+                        signal: controller.signal,
+                    });
+                    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 AuthenticationError(errorMessage);
+                            case 404:
+                                throw new NotFoundError(errorMessage);
+                            case 429:
+                                const retryAfter = response.headers.get('Retry-After');
+                                const rateLimitError = new 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 ServerError(errorMessage, response.status);
+                            default:
+                                throw new OilPriceAPIError(errorMessage, response.status, 'HTTP_ERROR');
+                        }
+                    }
+                    // Parse successful response
+                    const responseData = await response.json();
+                    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
+                    this.log('Returning data as-is');
+                    return responseData.data;
+                }
+                catch (error) {
+                    // Handle abort (timeout)
+                    if (error instanceof Error && error.name === 'AbortError') {
+                        throw new 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 OilPriceAPIError && !this.isRetryable(error)) {
+                    throw error;
+                }
+                // If this was our last attempt, throw the error
+                if (attempt === this.retries) {
+                    if (error instanceof OilPriceAPIError) {
+                        throw error;
+                    }
+                    // Wrap fetch errors (network issues, etc.)
+                    if (error instanceof Error) {
+                        throw new 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 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;
+        }
+        return this.request('/v1/prices', params);
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Base error class for all Oil Price API errors
+ */
+export declare class OilPriceAPIError extends Error {
+    /**
+     * HTTP status code (if applicable)
+     */
+    statusCode?: number;
+    /**
+     * Error code from the API
+     */
+    code?: string;
+    constructor(message: string, statusCode?: number, code?: string);
+}
+/**
+ * Thrown when API authentication fails (401)
+ */
+export declare class AuthenticationError extends OilPriceAPIError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when rate limit is exceeded (429)
+ */
+export declare class RateLimitError extends OilPriceAPIError {
+    /**
+     * Number of seconds until rate limit resets
+     */
+    retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
+/**
+ * Thrown when requested resource is not found (404)
+ */
+export declare class NotFoundError extends OilPriceAPIError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when server returns 5xx error
+ */
+export declare class ServerError extends OilPriceAPIError {
+    constructor(message?: string, statusCode?: number);
+}
+/**
+ * Thrown when request exceeds timeout
+ */
+export declare class TimeoutError extends OilPriceAPIError {
+    constructor(message: string | undefined, timeout: number);
+}

package/dist/errors.js

@@ -0,0 +1,61 @@
+/**
+ * Base error class for all Oil Price API errors
+ */
+export 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);
+        }
+    }
+}
+/**
+ * Thrown when API authentication fails (401)
+ */
+export class AuthenticationError extends OilPriceAPIError {
+    constructor(message = 'Invalid API key') {
+        super(message, 401, 'AUTHENTICATION_ERROR');
+        this.name = 'AuthenticationError';
+    }
+}
+/**
+ * Thrown when rate limit is exceeded (429)
+ */
+export class RateLimitError extends OilPriceAPIError {
+    constructor(message = 'Rate limit exceeded', retryAfter) {
+        super(message, 429, 'RATE_LIMIT_ERROR');
+        this.name = 'RateLimitError';
+        this.retryAfter = retryAfter;
+    }
+}
+/**
+ * Thrown when requested resource is not found (404)
+ */
+export class NotFoundError extends OilPriceAPIError {
+    constructor(message = 'Resource not found') {
+        super(message, 404, 'NOT_FOUND_ERROR');
+        this.name = 'NotFoundError';
+    }
+}
+/**
+ * Thrown when server returns 5xx error
+ */
+export class ServerError extends OilPriceAPIError {
+    constructor(message = 'Internal server error', statusCode = 500) {
+        super(message, statusCode, 'SERVER_ERROR');
+        this.name = 'ServerError';
+    }
+}
+/**
+ * Thrown when request exceeds timeout
+ */
+export class TimeoutError extends OilPriceAPIError {
+    constructor(message = 'Request timeout', timeout) {
+        super(`${message} (${timeout}ms)`, undefined, 'TIMEOUT_ERROR');
+        this.name = 'TimeoutError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Official Node.js SDK for Oil Price API
+ *
+ * Get real-time and historical oil & commodity prices in your Node.js applications.
+ *
+ * @packageDocumentation
+ */
+export { OilPriceAPI } from './client.js';
+export type { OilPriceAPIConfig, RetryStrategy, Price, LatestPricesOptions, HistoricalPricesOptions, HistoricalPeriod, } from './types.js';
+export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, TimeoutError, } from './errors.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * Official Node.js SDK for Oil Price API
+ *
+ * Get real-time and historical oil & commodity prices in your Node.js applications.
+ *
+ * @packageDocumentation
+ */
+export { OilPriceAPI } from './client.js';
+export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, TimeoutError, } from './errors.js';

package/dist/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Retry backoff strategy
+ */
+export type RetryStrategy = 'exponential' | 'linear' | 'fixed';
+/**
+ * Configuration options for OilPriceAPI client
+ */
+export interface OilPriceAPIConfig {
+    /**
+     * Your API key from https://www.oilpriceapi.com
+     */
+    apiKey: string;
+    /**
+     * Base URL for the API (optional, for testing)
+     * @default "https://api.oilpriceapi.com"
+     */
+    baseUrl?: string;
+    /**
+     * Maximum number of retry attempts for failed requests
+     * @default 3
+     */
+    retries?: number;
+    /**
+     * Initial delay between retries in milliseconds
+     * @default 1000
+     */
+    retryDelay?: number;
+    /**
+     * Retry backoff strategy
+     * @default "exponential"
+     */
+    retryStrategy?: RetryStrategy;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Enable debug logging to console
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Represents a single price data point
+ */
+export interface Price {
+    /**
+     * Commodity code (e.g., "WTI_USD", "BRENT_CRUDE_USD")
+     */
+    code: string;
+    /**
+     * Current price value
+     */
+    price: number;
+    /**
+     * Formatted price string (e.g., "$74.25")
+     */
+    formatted: string;
+    /**
+     * Currency code (e.g., "USD")
+     */
+    currency: string;
+    /**
+     * ISO 8601 timestamp of when this price was recorded
+     */
+    created_at: string;
+    /**
+     * Type of price (e.g., "spot_price")
+     */
+    type: string;
+    /**
+     * Data source (e.g., "oilprice.ft", "internal")
+     */
+    source: string;
+    /**
+     * Price changes over different time periods (24h, 7d, 30d, 90d)
+     */
+    changes?: {
+        '24h'?: {
+            amount: number;
+            percent: number;
+            previous_price: number;
+        };
+        '7d'?: {
+            amount: number;
+            percent: number;
+            previous_price: number;
+        };
+        '30d'?: {
+            amount: number;
+            percent: number;
+            previous_price: number;
+        };
+        '90d'?: {
+            amount: number;
+            percent: number;
+            previous_price: number;
+        };
+    };
+    /**
+     * Additional metadata about the source
+     */
+    metadata?: {
+        source: string;
+        source_description?: string;
+    };
+}
+/**
+ * Options for fetching latest prices
+ */
+export interface LatestPricesOptions {
+    /**
+     * Filter by specific commodity code (optional)
+     * Example: "WTI_USD", "BRENT_CRUDE_USD"
+     */
+    commodity?: string;
+}
+/**
+ * Time period options for historical data
+ */
+export type HistoricalPeriod = 'past_week' | 'past_month' | 'past_year';
+/**
+ * Options for fetching historical prices
+ */
+export interface HistoricalPricesOptions {
+    /**
+     * Predefined time period (alternative to startDate/endDate)
+     */
+    period?: HistoricalPeriod;
+    /**
+     * Filter by specific commodity code (optional)
+     */
+    commodity?: string;
+    /**
+     * Start date in ISO 8601 format (YYYY-MM-DD)
+     * Example: "2024-01-01"
+     */
+    startDate?: string;
+    /**
+     * End date in ISO 8601 format (YYYY-MM-DD)
+     * Example: "2024-12-31"
+     */
+    endDate?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "oilpriceapi",
+  "version": "0.2.0",
+  "description": "Official Node.js SDK for Oil Price API - Real-time and historical oil & commodity prices",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "oil",
+    "price",
+    "commodity",
+    "api",
+    "brent",
+    "wti",
+    "crude",
+    "gasoline",
+    "diesel",
+    "natural-gas",
+    "energy",
+    "trading"
+  ],
+  "author": "Oil Price API <karl@oilpriceapi.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OilpriceAPI/oilpriceapi-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OilpriceAPI/oilpriceapi-node/issues"
+  },
+  "homepage": "https://www.oilpriceapi.com",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  }
+}