oilpriceapi 0.5.1 → 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

@@ -1,6 +1,7 @@
 import { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, TimeoutError, } from './errors.js';
 import { DieselResource } from './resources/diesel.js';
 import { AlertsResource } from './resources/alerts.js';
+import { SDK_VERSION, SDK_NAME, buildUserAgent } from './version.js';
 /**
  * Official Node.js client for Oil Price API
  *
@@ -126,9 +127,9 @@ export class OilPriceAPI {
                         headers: {
                             'Authorization': `Bearer ${this.apiKey}`,
                             'Content-Type': 'application/json',
-                            'User-Agent': 'oilpriceapi-node/0.5.1 node/' + process.version,
-                            'X-Api-Client': 'oilpriceapi-node',
-                            'X-Client-Version': '0.5.1',
+                            'User-Agent': buildUserAgent(),
+                            'X-Api-Client': SDK_NAME,
+                            'X-Client-Version': SDK_VERSION,
                         },
                         signal: controller.signal,
                     });
@@ -293,7 +294,28 @@ export class OilPriceAPI {
         if (options?.endDate) {
             params.end_date = options.endDate;
         }
-        return this.request('/v1/prices', params);
+        // 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
+        // This was the same bug that affected the Python SDK (fixed in v1.4.4)
+        // Issue: SDK was returning wrong dates for historical queries
+        // Root Cause: Backend has_scope :by_period not working on /v1/prices
+        // Solution: Use /v1/prices/past_year which uses direct WHERE clauses
+        return this.request('/v1/prices/past_year', params);
     }
     /**
      * Get metadata for all supported commodities

package/dist/index.d.ts

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

@@ -6,4 +6,5 @@
  * @packageDocumentation
  */
 export { OilPriceAPI } from './client.js';
+export { SDK_VERSION, SDK_NAME } from './version.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

@@ -0,0 +1,18 @@
+/**
+ * SDK Version - centralized to ensure consistency across all headers
+ *
+ * This version must be updated when publishing a new release.
+ * It's used in:
+ * - User-Agent header: oilpriceapi-node/{version}
+ * - X-Client-Version header
+ * - Package.json (should match)
+ */
+export declare const SDK_VERSION = "0.6.0";
+/**
+ * SDK identifier used in User-Agent and X-Api-Client headers
+ */
+export declare const SDK_NAME = "oilpriceapi-node";
+/**
+ * Build the full User-Agent string
+ */
+export declare function buildUserAgent(): string;

package/dist/version.js

@@ -0,0 +1,20 @@
+/**
+ * SDK Version - centralized to ensure consistency across all headers
+ *
+ * This version must be updated when publishing a new release.
+ * It's used in:
+ * - User-Agent header: oilpriceapi-node/{version}
+ * - X-Client-Version header
+ * - Package.json (should match)
+ */
+export const SDK_VERSION = '0.6.0';
+/**
+ * SDK identifier used in User-Agent and X-Api-Client headers
+ */
+export const SDK_NAME = 'oilpriceapi-node';
+/**
+ * Build the full User-Agent string
+ */
+export function buildUserAgent() {
+    return `${SDK_NAME}/${SDK_VERSION} node/${process.version}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oilpriceapi",
-  "version": "0.5.1",
+  "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",
@@ -55,6 +55,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
+    "@vitest/coverage-v8": "^1.0.0",
     "typescript": "^5.3.0",
     "vitest": "^1.0.0"
   }