oilpriceapi 0.3.0 → 0.3.2

package/README.md

@@ -51,13 +51,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 +67,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)
@@ -171,81 +170,47 @@ const prices = await client.getLatestPrices();
 // [OilPriceAPI 2024-11-24T20:28:23.394Z] Response data received { status: 'success', hasData: true }
 ```
 
-## Integration Examples
+## Examples
 
-### Express.js
+See the [`examples/`](./examples) directory for complete, runnable code examples:
 
-```typescript
-import express from 'express';
-import { OilPriceAPI } from 'oilpriceapi';
+- **[basic.ts](./examples/basic.ts)** - Simple usage patterns
+- **[express.ts](./examples/express.ts)** - Express.js API server integration
+- **[nextjs-api-route.ts](./examples/nextjs-api-route.ts)** - Next.js API route handler
+- **[error-handling.ts](./examples/error-handling.ts)** - Comprehensive error handling
+- **[commodities.ts](./examples/commodities.ts)** - Working with commodity metadata
 
-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
-    });
-  }
-});
+### Quick Examples
 
-app.listen(3000, () => {
-  console.log('Server running on port 3000');
-});
+**Get Latest Price:**
+```typescript
+const prices = await client.getLatestPrices({ commodity: 'WTI_USD' });
+console.log(prices[0].formatted); // "$74.25"
 ```
 
-### Next.js API Route
-
+**Historical Data:**
 ```typescript
-// app/api/prices/route.ts
-import { OilPriceAPI } from 'oilpriceapi';
-
-const client = new OilPriceAPI({
-  apiKey: process.env.OIL_PRICE_API_KEY
+const history = await client.getHistoricalPrices({
+  commodity: 'BRENT_CRUDE_USD',
+  period: 'past_week'
 });
-
-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
-
+**Commodity Metadata:**
 ```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}`);
+const { commodities } = await client.getCommodities();
+console.log(`Found ${commodities.length} commodities`);
+```
 
-  if (price < 70) {
-    console.log('🚨 ALERT: WTI below $70!');
-    // Send notification, email, etc.
+**Error Handling:**
+```typescript
+try {
+  const prices = await client.getLatestPrices();
+} catch (error) {
+  if (error instanceof RateLimitError) {
+    console.log('Rate limited, retry after:', error.retryAfter);
   }
 }
-
-// Check every 5 minutes
-setInterval(checkPrice, 5 * 60 * 1000);
-checkPrice(); // Run immediately
 ```
 
 ## API Reference
@@ -287,6 +252,27 @@ Get historical prices for a time period.
 
 **Returns:** `Promise<Price[]>`
 
+##### `getCommodities()`
+
+Get metadata for all supported commodities.
+
+**Returns:** `Promise<CommoditiesResponse>` - Object with `commodities` array
+
+##### `getCommodityCategories()`
+
+Get all commodity categories with their commodities.
+
+**Returns:** `Promise<CategoriesResponse>` - Object with category keys mapped to category objects
+
+##### `getCommodity(code)`
+
+Get metadata for a specific commodity by code.
+
+**Parameters:**
+- `code` (string, required) - Commodity code (e.g., "WTI_USD")
+
+**Returns:** `Promise<Commodity>` - Commodity metadata object
+
 ### Types
 
 #### `Price`

package/dist/client.js

@@ -35,7 +35,7 @@ export class OilPriceAPI {
         this.retries = config.retries !== undefined ? config.retries : 3;
         this.retryDelay = config.retryDelay || 1000;
         this.retryStrategy = config.retryStrategy || 'exponential';
-        this.timeout = config.timeout || 30000;
+        this.timeout = config.timeout || 90000; // 90 seconds for slow historical queries
         this.debug = config.debug || false;
     }
     /**
@@ -121,7 +121,10 @@ export class OilPriceAPI {
                         headers: {
                             'Authorization': `Bearer ${this.apiKey}`,
                             'Content-Type': 'application/json',
-                            'User-Agent': 'oilpriceapi-node/0.3.0',
+                            'User-Agent': 'oilpriceapi-node/0.3.2',
+                            'X-SDK-Language': 'javascript',
+                            'X-SDK-Version': '0.3.2',
+                            'X-Client-Type': 'sdk',
                         },
                         signal: controller.signal,
                     });

package/dist/types.d.ts

@@ -32,7 +32,7 @@ export interface OilPriceAPIConfig {
     retryStrategy?: RetryStrategy;
     /**
      * Request timeout in milliseconds
-     * @default 30000 (30 seconds)
+     * @default 90000 (90 seconds)
      */
     timeout?: number;
     /**

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "oilpriceapi",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Official Node.js SDK for Oil Price API - Real-time and historical oil & commodity prices",
+  "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {