feat: Add telemetry headers for app tracking (v0.7.0)

- Add appUrl and appName config options for SDK telemetry
- Send X-SDK-Name, X-SDK-Version headers on every request
- Send X-App-URL, X-App-Name headers when configured (10% bonus!)
- Rename headers from X-Api-Client to X-SDK-Name for consistency
- Bump version to 0.7.0

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: karlwaldman

package.json

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

src/client.ts

@@ -18,6 +18,7 @@ import {
 } 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
@@ -53,6 +54,8 @@ export class OilPriceAPI {
   private retryStrategy: RetryStrategy;
   private timeout: number;
   private debug: boolean;
+  private appUrl?: string;
+  private appName?: string;
 
   /**
    * Diesel prices resource (state averages + station-level pricing)
@@ -76,6 +79,8 @@ export class OilPriceAPI {
     this.retryStrategy = config.retryStrategy || 'exponential';
     this.timeout = config.timeout || 90000; // 90 seconds for slow historical queries
     this.debug = config.debug || false;
+    this.appUrl = config.appUrl;
+    this.appName = config.appName;
 
     // Initialize resources
     this.diesel = new DieselResource(this);
@@ -176,15 +181,26 @@ export class OilPriceAPI {
         const timeoutId = setTimeout(() => controller.abort(), this.timeout);
 
         try {
+          // Build headers with optional telemetry
+          const headers: Record<string, string> = {
+            'Authorization': `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+            'User-Agent': buildUserAgent(),
+            'X-SDK-Name': SDK_NAME,
+            'X-SDK-Version': SDK_VERSION,
+          };
+
+          // Add optional telemetry headers (10% bonus for appUrl!)
+          if (this.appUrl) {
+            headers['X-App-URL'] = this.appUrl;
+          }
+          if (this.appName) {
+            headers['X-App-Name'] = this.appName;
+          }
+
           const response = await fetch(url.toString(), {
             method: 'GET',
-            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',
-            },
+            headers,
             signal: controller.signal,
           });
 
@@ -386,7 +402,31 @@ export class OilPriceAPI {
       params.end_date = options.endDate;
     }
 
-    return this.request<Price[]>('/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<Price[]>('/v1/prices/past_year', params);
   }
 
   /**

src/index.ts

@@ -7,13 +7,15 @@
  */
 
 export { OilPriceAPI } from './client.js';
+export { SDK_VERSION, SDK_NAME } from './version.js';
 export type {
   OilPriceAPIConfig,
   RetryStrategy,
   Price,
   LatestPricesOptions,
   HistoricalPricesOptions,
   HistoricalPeriod,
+  AggregationInterval,
   Commodity,
   CommoditiesResponse,
   CommodityCategory,

src/types.ts

@@ -47,6 +47,20 @@ export interface OilPriceAPIConfig {
    * @default false
    */
   debug?: boolean;
+
+  /**
+   * Your application's URL (optional, for telemetry)
+   * Helps us understand how the API is being used and may unlock
+   * a 10% bonus to your request limit.
+   * @example "https://myapp.com"
+   */
+  appUrl?: string;
+
+  /**
+   * Your application's name (optional, for telemetry)
+   * @example "MyFuelPriceTracker"
+   */
+  appName?: string;
 }
 
 /**
@@ -139,6 +153,15 @@ export interface LatestPricesOptions {
  */
 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
  */
@@ -164,6 +187,31 @@ 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;
 }
 
 /**

src/version.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.7.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(): string {
+  return `${SDK_NAME}/${SDK_VERSION} node/${process.version}`;
+}