oilpriceapi 0.3.1 → 0.5.0

package/README.md

@@ -10,12 +10,14 @@ Official Node.js SDK for [Oil Price API](https://www.oilpriceapi.com) - Get real
 - ✅ **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
+- 🎯 **Comprehensive** - Covers all API endpoints including diesel prices & alerts
 - 🚀 **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
+- ⛽ **NEW v0.4.0** - Diesel prices (state averages + station-level pricing)
+- 🔔 **NEW v0.5.0** - Price alerts with webhook notifications
 
 ## Installation
 
@@ -51,13 +53,12 @@ const prices = await client.getLatestPrices();
 // [
 //   {
 //     code: 'WTI_USD',
-//     name: 'WTI Crude Oil',
-//     value: 74.25,
+//     price: 74.25,
+//     formatted: '$74.25',
 //     currency: 'USD',
-//     unit: 'barrel',
-//     timestamp: '2024-11-24T12:00:00Z',
+//     type: 'spot_price',
 //     created_at: '2024-11-24T12:01:00Z',
-//     updated_at: '2024-11-24T12:01:00Z'
+//     source: 'oilprice.investing_com'
 //   },
 //   // ... more prices
 // ]
@@ -68,11 +69,11 @@ const prices = await client.getLatestPrices();
 ```typescript
 // Get only WTI crude oil price
 const wti = await client.getLatestPrices({ commodity: 'WTI_USD' });
-console.log(`WTI: $${wti[0].value} per barrel`);
+console.log(`WTI: ${wti[0].formatted} per barrel`);
 
 // Get only Brent crude price
 const brent = await client.getLatestPrices({ commodity: 'BRENT_CRUDE_USD' });
-console.log(`Brent: $${brent[0].value} per barrel`);
+console.log(`Brent: ${brent[0].formatted} per barrel`);
 ```
 
 ### Get Historical Prices (Past Week)
@@ -98,6 +99,176 @@ const prices = await client.getHistoricalPrices({
 console.log(`Got ${prices.length} data points for 2024`);
 ```
 
+### Get Diesel Prices (New in v0.4.0)
+
+#### Get State Average Diesel Price
+
+```typescript
+// Get California diesel price
+const caPrice = await client.diesel.getPrice('CA');
+console.log(`California diesel: $${caPrice.price}/gallon`);
+console.log(`Source: ${caPrice.source}`);
+console.log(`Last updated: ${caPrice.updated_at}`);
+
+// Example output:
+// California diesel: $3.89/gallon
+// Source: EIA
+// Last updated: 2025-12-15T10:00:00Z
+```
+
+#### Get Nearby Diesel Stations
+
+```typescript
+// Find diesel stations near San Francisco
+const result = await client.diesel.getStations({
+  lat: 37.7749,   // San Francisco latitude
+  lng: -122.4194, // San Francisco longitude
+  radius: 8047    // 5 miles in meters (default if not specified)
+});
+
+console.log(`Regional average: $${result.regional_average.price}/gallon`);
+console.log(`Found ${result.stations.length} stations within ${result.search_area.radius_miles} miles`);
+
+// Print each station
+result.stations.forEach(station => {
+  console.log(`\n${station.name}`);
+  console.log(`  Address: ${station.address}`);
+  console.log(`  Price: ${station.formatted_price}`);
+  console.log(`  ${station.price_vs_average}`);
+});
+
+// Example output:
+// Regional average: $3.89/gallon
+// Found 12 stations within 5 miles
+//
+// Chevron Station
+//   Address: 123 Main St, San Francisco, CA
+//   Price: $3.75
+//   $0.14 cheaper than regional average
+//
+// Shell Gas
+//   Address: 456 Oak Ave, San Francisco, CA
+//   Price: $3.89
+//   Same as regional average
+```
+
+#### Find Cheapest Diesel Station
+
+```typescript
+const result = await client.diesel.getStations({
+  lat: 34.0522,   // Los Angeles
+  lng: -118.2437,
+  radius: 5000    // ~3 miles
+});
+
+// Find the cheapest station
+const cheapest = result.stations.reduce((min, station) =>
+  station.diesel_price < min.diesel_price ? station : min
+);
+
+console.log(`Cheapest diesel: ${cheapest.name} at ${cheapest.formatted_price}`);
+console.log(`Savings: ${Math.abs(cheapest.price_delta!).toFixed(2)} per gallon vs regional average`);
+```
+
+**Note:** Station-level diesel prices are available on paid tiers (Exploration and above). State averages are free.
+
+### Price Alerts (New in v0.5.0)
+
+#### Create a Price Alert
+
+```typescript
+// Create an alert when Brent crude exceeds $85
+const alert = await client.alerts.create({
+  name: 'Brent High Alert',
+  commodity_code: 'BRENT_CRUDE_USD',
+  condition_operator: 'greater_than',
+  condition_value: 85.00,
+  webhook_url: 'https://your-app.com/webhooks/price-alert',
+  enabled: true,
+  cooldown_minutes: 60  // Wait 60 minutes between triggers
+});
+
+console.log(`Alert created: ${alert.name} (ID: ${alert.id})`);
+```
+
+#### List All Alerts
+
+```typescript
+const alerts = await client.alerts.list();
+
+alerts.forEach(alert => {
+  console.log(`${alert.name}: ${alert.commodity_code} ${alert.condition_operator} ${alert.condition_value}`);
+  console.log(`  Status: ${alert.enabled ? 'Active' : 'Disabled'}`);
+  console.log(`  Triggers: ${alert.trigger_count}`);
+  console.log(`  Last triggered: ${alert.last_triggered_at || 'Never'}`);
+});
+```
+
+#### Update an Alert
+
+```typescript
+// Disable an alert
+await client.alerts.update(alertId, { enabled: false });
+
+// Change threshold and cooldown
+await client.alerts.update(alertId, {
+  condition_value: 90.00,
+  cooldown_minutes: 120
+});
+
+// Update webhook URL
+await client.alerts.update(alertId, {
+  webhook_url: 'https://new-app.com/webhook'
+});
+```
+
+#### Delete an Alert
+
+```typescript
+await client.alerts.delete(alertId);
+console.log('Alert deleted successfully');
+```
+
+#### Test Webhook Endpoint
+
+```typescript
+const result = await client.alerts.testWebhook('https://your-app.com/webhook');
+
+if (result.success) {
+  console.log(`Webhook OK (${result.status_code}) - ${result.response_time_ms}ms`);
+} else {
+  console.error(`Webhook failed: ${result.error}`);
+}
+```
+
+**Alert Operators:**
+- `greater_than` - Trigger when price exceeds threshold
+- `less_than` - Trigger when price falls below threshold
+- `equals` - Trigger when price matches threshold exactly
+- `greater_than_or_equal` - Trigger when price meets or exceeds threshold
+- `less_than_or_equal` - Trigger when price is at or below threshold
+
+**Webhook Payload Example:**
+When an alert triggers, a POST request is sent to your webhook URL with:
+```json
+{
+  "event": "price_alert.triggered",
+  "alert_id": "550e8400-e29b-41d4-a716-446655440000",
+  "alert_name": "Brent High Alert",
+  "commodity_code": "BRENT_CRUDE_USD",
+  "condition_operator": "greater_than",
+  "condition_value": 85.00,
+  "current_price": 86.50,
+  "triggered_at": "2025-12-15T14:30:00Z"
+}
+```
+
+**Limits:**
+- Maximum 100 alerts per user
+- Cooldown period: 0-1440 minutes (24 hours)
+- Condition value: Must be between $0.01 and $1,000,000
+- Webhook URL: Must use HTTPS protocol
+
 ### Advanced Configuration
 
 ```typescript
@@ -203,6 +374,39 @@ const { commodities } = await client.getCommodities();
 console.log(`Found ${commodities.length} commodities`);
 ```
 
+**Diesel Prices:**
+```typescript
+// State average (free)
+const caPrice = await client.diesel.getPrice('CA');
+console.log(`CA diesel: $${caPrice.price}/gal`);
+
+// Nearby stations (paid tiers)
+const stations = await client.diesel.getStations({
+  lat: 37.7749,
+  lng: -122.4194,
+  radius: 8047  // 5 miles
+});
+console.log(`Found ${stations.stations.length} stations`);
+```
+
+**Price Alerts:**
+```typescript
+// Create an alert
+const alert = await client.alerts.create({
+  name: 'Brent High Alert',
+  commodity_code: 'BRENT_CRUDE_USD',
+  condition_operator: 'greater_than',
+  condition_value: 85.00,
+  webhook_url: 'https://your-app.com/webhook'
+});
+
+// List all alerts
+const alerts = await client.alerts.list();
+
+// Update an alert
+await client.alerts.update(alert.id, { enabled: false });
+```
+
 **Error Handling:**
 ```typescript
 try {
@@ -274,6 +478,55 @@ Get metadata for a specific commodity by code.
 
 **Returns:** `Promise<Commodity>` - Commodity metadata object
 
+### `client.diesel`
+
+Resource for diesel price data (state averages and station-level pricing).
+
+##### `diesel.getPrice(state)`
+
+Get average diesel price for a US state from EIA data.
+
+**Parameters:**
+- `state` (string, required) - Two-letter US state code (e.g., "CA", "TX", "NY")
+
+**Returns:** `Promise<DieselPrice>`
+
+**Example:**
+```typescript
+const caPrice = await client.diesel.getPrice('CA');
+console.log(`California: $${caPrice.price}/gallon`);
+```
+
+##### `diesel.getStations(options)`
+
+Get nearby diesel stations with current pricing from Google Maps data.
+
+**Parameters:**
+- `options.lat` (number, required) - Latitude (-90 to 90)
+- `options.lng` (number, required) - Longitude (-180 to 180)
+- `options.radius` (number, optional) - Search radius in meters (default: 8047 = 5 miles, max: 50000)
+
+**Returns:** `Promise<DieselStationsResponse>`
+
+**Tier Requirements:** Available on paid tiers (Exploration and above)
+
+**Example:**
+```typescript
+const result = await client.diesel.getStations({
+  lat: 37.7749,
+  lng: -122.4194,
+  radius: 8047  // 5 miles
+});
+
+console.log(`Found ${result.stations.length} stations`);
+console.log(`Regional average: $${result.regional_average.price}/gallon`);
+
+const cheapest = result.stations.reduce((min, s) =>
+  s.diesel_price < min.diesel_price ? s : min
+);
+console.log(`Cheapest: ${cheapest.name} at ${cheapest.formatted_price}`);
+```
+
 ### Types
 
 #### `Price`
@@ -291,6 +544,74 @@ interface Price {
 }
 ```
 
+#### `DieselPrice`
+
+```typescript
+interface DieselPrice {
+  state: string;          // State code (e.g., "CA", "TX")
+  price: number;          // Average diesel price in USD per gallon
+  currency: string;       // Currency code (always "USD")
+  unit: string;           // Unit of measurement (always "gallon")
+  granularity: string;    // Level (e.g., "state", "national")
+  source: string;         // Data source (e.g., "EIA")
+  updated_at: string;     // ISO 8601 timestamp of last update
+  cached?: boolean;       // Whether served from cache
+}
+```
+
+#### `DieselStation`
+
+```typescript
+interface DieselStation {
+  name: string;           // Station name
+  address: string;        // Full street address
+  location: {
+    lat: number;          // Latitude
+    lng: number;          // Longitude
+  };
+  diesel_price: number;   // Price at this station (USD per gallon)
+  formatted_price: string;// Formatted price (e.g., "$3.89")
+  currency: string;       // Currency code (always "USD")
+  unit: string;           // Unit (always "gallon")
+  price_delta?: number;   // Difference from regional average
+  price_vs_average?: string; // Human-readable comparison
+  fuel_types?: string[];  // Available fuel types
+  last_updated?: string;  // ISO 8601 timestamp
+}
+```
+
+#### `DieselStationsResponse`
+
+```typescript
+interface DieselStationsResponse {
+  regional_average: {
+    price: number;        // Regional average price
+    currency: string;     // Currency code
+    unit: string;         // Unit
+    region: string;       // Region name
+    granularity: string;  // Granularity level
+    source: string;       // Data source
+  };
+  stations: DieselStation[]; // List of nearby stations
+  search_area: {
+    center: {
+      lat: number;        // Search center latitude
+      lng: number;        // Search center longitude
+    };
+    radius_meters: number;// Search radius in meters
+    radius_miles: number; // Search radius in miles
+  };
+  metadata: {
+    total_stations: number; // Number of stations found
+    source: string;        // Data source
+    cached: boolean;       // Whether served from cache
+    api_cost: number;      // Cost in dollars
+    timestamp: string;     // ISO 8601 timestamp
+    cache_age_hours?: number; // Cache age in hours
+  };
+}
+```
+
 ### Error Classes
 
 All errors extend `OilPriceAPIError`:
@@ -305,7 +626,7 @@ All errors extend `OilPriceAPIError`:
 The API provides prices for the following commodities:
 
 - **Crude Oil**: WTI, Brent Crude
-- **Refined Products**: Gasoline, Diesel, Heating Oil, Jet Fuel
+- **Refined Products**: Gasoline, Diesel (state averages + station-level), Heating Oil, Jet Fuel
 - **Natural Gas**: US Natural Gas, EU Natural Gas, UK Natural Gas
 - **And more...**
 
@@ -313,7 +634,7 @@ See the [full list of commodities](https://www.oilpriceapi.com/commodities) in t
 
 ## Pricing & Rate Limits
 
-- **Free Tier**: 1,000 requests/month
+- **Free Tier**: 100 requests (lifetime)
 - **Starter**: 50,000 requests/month - $49/mo
 - **Professional**: 100,000 requests/month - $99/mo
 - **Business**: 200,000 requests/month - $199/mo

package/dist/client.d.ts

@@ -1,4 +1,6 @@
 import type { OilPriceAPIConfig, Price, LatestPricesOptions, HistoricalPricesOptions, Commodity, CommoditiesResponse, CategoriesResponse } from './types.js';
+import { DieselResource } from './resources/diesel.js';
+import { AlertsResource } from './resources/alerts.js';
 /**
  * Official Node.js client for Oil Price API
  *
@@ -33,6 +35,14 @@ export declare class OilPriceAPI {
     private retryStrategy;
     private timeout;
     private debug;
+    /**
+     * Diesel prices resource (state averages + station-level pricing)
+     */
+    readonly diesel: DieselResource;
+    /**
+     * Price alerts resource (create, manage, and monitor alerts)
+     */
+    readonly alerts: AlertsResource;
     constructor(config: OilPriceAPIConfig);
     /**
      * Log debug messages if debug mode is enabled

package/dist/client.js

@@ -1,4 +1,6 @@
 import { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, TimeoutError, } from './errors.js';
+import { DieselResource } from './resources/diesel.js';
+import { AlertsResource } from './resources/alerts.js';
 /**
  * Official Node.js client for Oil Price API
  *
@@ -37,6 +39,9 @@ export class OilPriceAPI {
         this.retryStrategy = config.retryStrategy || 'exponential';
         this.timeout = config.timeout || 90000; // 90 seconds for slow historical queries
         this.debug = config.debug || false;
+        // Initialize resources
+        this.diesel = new DieselResource(this);
+        this.alerts = new AlertsResource(this);
     }
     /**
      * Log debug messages if debug mode is enabled
@@ -121,7 +126,10 @@ export class OilPriceAPI {
                         headers: {
                             'Authorization': `Bearer ${this.apiKey}`,
                             'Content-Type': 'application/json',
-                            'User-Agent': 'oilpriceapi-node/0.3.1',
+                            'User-Agent': 'oilpriceapi-node/0.5.0',
+                            'X-SDK-Language': 'javascript',
+                            'X-SDK-Version': '0.5.0',
+                            'X-Client-Type': 'sdk',
                         },
                         signal: controller.signal,
                     });

package/dist/index.d.ts

@@ -7,4 +7,6 @@
  */
 export { OilPriceAPI } from './client.js';
 export type { OilPriceAPIConfig, RetryStrategy, Price, LatestPricesOptions, HistoricalPricesOptions, HistoricalPeriod, Commodity, CommoditiesResponse, CommodityCategory, CategoriesResponse, } from './types.js';
+export type { DieselPrice, DieselStation, DieselStationsResponse, GetDieselStationsOptions, } from './resources/diesel.js';
+export type { PriceAlert, CreateAlertParams, UpdateAlertParams, AlertOperator, WebhookTestResponse, } from './resources/alerts.js';
 export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, TimeoutError, } from './errors.js';