oilpriceapi 0.2.0 → 0.3.1

package/README.md

@@ -171,81 +171,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 +253,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.d.ts

@@ -1,4 +1,4 @@
-import type { OilPriceAPIConfig, Price, LatestPricesOptions, HistoricalPricesOptions } from './types.js';
+import type { OilPriceAPIConfig, Price, LatestPricesOptions, HistoricalPricesOptions, Commodity, CommoditiesResponse, CategoriesResponse } from './types.js';
 /**
  * Official Node.js client for Oil Price API
  *
@@ -93,4 +93,42 @@ export declare class OilPriceAPI {
      * ```
      */
     getHistoricalPrices(options?: HistoricalPricesOptions): Promise<Price[]>;
+    /**
+     * 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
+     * ```
+     */
+    getCommodities(): Promise<CommoditiesResponse>;
+    /**
+     * 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
+     * ```
+     */
+    getCommodityCategories(): Promise<CategoriesResponse>;
+    /**
+     * 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"
+     * ```
+     */
+    getCommodity(code: string): Promise<Commodity>;
 }

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,7 @@ export class OilPriceAPI {
                         headers: {
                             'Authorization': `Bearer ${this.apiKey}`,
                             'Content-Type': 'application/json',
-                            'User-Agent': 'oilpriceapi-node/0.2.0',
+                            'User-Agent': 'oilpriceapi-node/0.3.1',
                         },
                         signal: controller.signal,
                     });
@@ -288,4 +288,48 @@ export class OilPriceAPI {
         }
         return this.request('/v1/prices', params);
     }
+    /**
+     * 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}`, {});
+    }
 }

package/dist/index.d.ts

@@ -6,5 +6,5 @@
  * @packageDocumentation
  */
 export { OilPriceAPI } from './client.js';
-export type { OilPriceAPIConfig, RetryStrategy, Price, LatestPricesOptions, HistoricalPricesOptions, HistoricalPeriod, } from './types.js';
+export type { OilPriceAPIConfig, RetryStrategy, Price, LatestPricesOptions, HistoricalPricesOptions, HistoricalPeriod, Commodity, CommoditiesResponse, CommodityCategory, CategoriesResponse, } from './types.js';
 export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, TimeoutError, } from './errors.js';

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;
     /**
@@ -143,3 +143,71 @@ export interface HistoricalPricesOptions {
      */
     endDate?: string;
 }
+/**
+ * Represents commodity metadata
+ */
+export interface Commodity {
+    /**
+     * Unique commodity identifier
+     */
+    code: string;
+    /**
+     * Human-readable commodity name
+     */
+    name: string;
+    /**
+     * Base currency for pricing
+     */
+    currency: string;
+    /**
+     * Commodity category (e.g., "oil", "gas", "renewable")
+     */
+    category: string;
+    /**
+     * Detailed description
+     */
+    description?: string;
+    /**
+     * Unit of measurement (e.g., "barrel", "gallon")
+     */
+    unit: string;
+    /**
+     * Detailed unit description
+     */
+    unit_description?: string;
+    /**
+     * Storage multiplier for price values
+     */
+    multiplier?: number;
+    /**
+     * Price validation ranges
+     */
+    validation?: {
+        min: number;
+        max: number;
+    };
+    /**
+     * Threshold for significant price change alerts
+     */
+    price_change_threshold?: number;
+}
+/**
+ * Response from /v1/commodities endpoint
+ */
+export interface CommoditiesResponse {
+    commodities: Commodity[];
+}
+/**
+ * Category with its commodities
+ */
+export interface CommodityCategory {
+    name: string;
+    commodities: Commodity[];
+}
+/**
+ * Response from /v1/commodities/categories endpoint
+ * Returns object with category keys mapped to CommodityCategory objects
+ */
+export interface CategoriesResponse {
+    [categoryKey: string]: CommodityCategory;
+}

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "oilpriceapi",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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": {
@@ -40,7 +41,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/OilpriceAPI/oilpriceapi-node.git"
+    "url": "git+https://github.com/OilpriceAPI/oilpriceapi-node.git"
   },
   "bugs": {
     "url": "https://github.com/OilpriceAPI/oilpriceapi-node/issues"