oilpriceapi 0.5.3 → 0.6.0

package/README.md

@@ -99,6 +99,25 @@ const prices = await client.getHistoricalPrices({
 console.log(`Got ${prices.length} data points for 2024`);
 ```
 
+### Performance Optimization (New in v0.6.0)
+
+For year-long queries, use the `interval` parameter to dramatically improve response times:
+
+```typescript
+// FAST: Daily aggregation returns 365 data points (~1 second)
+const yearlyPrices = await client.getHistoricalPrices({
+  period: 'past_year',
+  commodity: 'BRENT_CRUDE_USD',
+  interval: 'daily'  // Options: 'raw', 'hourly', 'daily', 'weekly', 'monthly'
+});
+
+console.log(`Got ${yearlyPrices.length} daily averages`);
+// Output: Got 365 daily averages
+
+// SLOW: Raw data returns 600k+ points (can take 74+ seconds)
+// Only use 'raw' when you need every individual price point
+```
+
 ### Get Diesel Prices (New in v0.4.0)
 
 #### Get State Average Diesel Price
@@ -454,6 +473,9 @@ Get historical prices for a time period.
 - `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)
+- `options.interval` (string, optional) - Aggregation interval: "raw", "hourly", "daily", "weekly", "monthly". **Performance tip:** Use "daily" for year-long queries (365 points vs 600k+ raw points)
+- `options.perPage` (number, optional) - Results per page (default: 100, max: 1000)
+- `options.page` (number, optional) - Page number for pagination (default: 1)
 
 **Returns:** `Promise<Price[]>`
 

package/dist/client.js

@@ -294,6 +294,20 @@ export class OilPriceAPI {
         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

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  */
 export { OilPriceAPI } from './client.js';
 export { SDK_VERSION, SDK_NAME } from './version.js';
-export type { OilPriceAPIConfig, RetryStrategy, Price, LatestPricesOptions, HistoricalPricesOptions, HistoricalPeriod, Commodity, CommoditiesResponse, CommodityCategory, CategoriesResponse, } from './types.js';
+export type { OilPriceAPIConfig, RetryStrategy, Price, LatestPricesOptions, HistoricalPricesOptions, HistoricalPeriod, AggregationInterval, 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';

package/dist/types.d.ts

@@ -120,6 +120,14 @@ export interface LatestPricesOptions {
  * Time period options for historical data
  */
 export type HistoricalPeriod = 'past_week' | 'past_month' | 'past_year';
+/**
+ * Aggregation interval for historical data
+ *
+ * PERFORMANCE TIP: Use 'daily' or 'weekly' for year-long queries to reduce
+ * response times from 74s to <1s. The 'raw' option returns individual price
+ * points which can be 600k+ records for a year of BRENT data.
+ */
+export type AggregationInterval = 'raw' | 'hourly' | 'daily' | 'weekly' | 'monthly';
 /**
  * Options for fetching historical prices
  */
@@ -142,6 +150,28 @@ export interface HistoricalPricesOptions {
      * Example: "2024-12-31"
      */
     endDate?: string;
+    /**
+     * Aggregation interval for the data
+     *
+     * PERFORMANCE: For year-long queries, use 'daily' (365 points) or 'weekly' (52 points)
+     * instead of 'raw' (600k+ points for BRENT) to dramatically improve response times.
+     *
+     * @default API default (raw for short periods, may be aggregated for long periods)
+     */
+    interval?: AggregationInterval;
+    /**
+     * Number of results per page
+     *
+     * @default 100 (API default)
+     * @max 1000
+     */
+    perPage?: number;
+    /**
+     * Page number for pagination (1-indexed)
+     *
+     * @default 1
+     */
+    page?: number;
 }
 /**
  * Represents commodity metadata

package/dist/version.d.ts

@@ -7,7 +7,7 @@
  * - X-Client-Version header
  * - Package.json (should match)
  */
-export declare const SDK_VERSION = "0.5.3";
+export declare const SDK_VERSION = "0.6.0";
 /**
  * SDK identifier used in User-Agent and X-Api-Client headers
  */

package/dist/version.js

@@ -7,7 +7,7 @@
  * - X-Client-Version header
  * - Package.json (should match)
  */
-export const SDK_VERSION = '0.5.3';
+export const SDK_VERSION = '0.6.0';
 /**
  * SDK identifier used in User-Agent and X-Api-Client headers
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oilpriceapi",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Official Node.js SDK for Oil Price API - Real-time and historical oil & commodity prices",
   "type": "module",
   "main": "./dist/index.js",