oilpriceapi 0.7.0 → 0.8.2

package/dist/resources/data-sources.js

@@ -3,6 +3,7 @@
  *
  * Manage custom data source integrations for Bring Your Own Source (BYOS) feature.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Data Sources Resource
  *
@@ -86,7 +87,7 @@ export class DataSourcesResource {
      */
     async get(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Data source ID must be a non-empty string");
+            throw new ValidationError("Data source ID must be a non-empty string");
         }
         const response = await this.client["request"](`/v1/data-sources/${id}`, {});
         return "data_source" in response ? response.data_source : response;
@@ -117,22 +118,17 @@ export class DataSourcesResource {
      */
     async create(params) {
         if (!params.name || typeof params.name !== "string") {
-            throw new Error("Data source name is required");
+            throw new ValidationError("Data source name is required");
         }
         if (!params.type) {
-            throw new Error("Data source type is required");
+            throw new ValidationError("Data source type is required");
         }
         if (!params.config || typeof params.config !== "object") {
-            throw new Error("Data source config is required");
+            throw new ValidationError("Data source config is required");
         }
-        const url = `${this.client["baseUrl"]}/v1/data-sources`;
-        const response = await fetch(url, {
+        const response = await this.client["request"]("/v1/data-sources", {}, {
             method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({
+            body: {
                 data_source: {
                     name: params.name,
                     type: params.type,
@@ -141,14 +137,9 @@ export class DataSourcesResource {
                     sync_frequency_minutes: params.sync_frequency_minutes ?? 60,
                     metadata: params.metadata,
                 },
-            }),
+            },
         });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to create data source: ${response.status} ${errorText}`);
-        }
-        const data = (await response.json());
-        return "data_source" in data ? data.data_source : data;
+        return "data_source" in response ? response.data_source : response;
     }
     /**
      * Update a data source
@@ -173,25 +164,13 @@ export class DataSourcesResource {
      */
     async update(id, params) {
         if (!id || typeof id !== "string") {
-            throw new Error("Data source ID must be a non-empty string");
+            throw new ValidationError("Data source ID must be a non-empty string");
         }
-        const url = `${this.client["baseUrl"]}/v1/data-sources/${id}`;
-        const response = await fetch(url, {
+        const response = await this.client["request"](`/v1/data-sources/${id}`, {}, {
             method: "PATCH",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({
-                data_source: params,
-            }),
+            body: { data_source: params },
         });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to update data source: ${response.status} ${errorText}`);
-        }
-        const data = (await response.json());
-        return "data_source" in data ? data.data_source : data;
+        return "data_source" in response ? response.data_source : response;
     }
     /**
      * Delete a data source
@@ -209,20 +188,9 @@ export class DataSourcesResource {
      */
     async delete(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Data source ID must be a non-empty string");
-        }
-        const url = `${this.client["baseUrl"]}/v1/data-sources/${id}`;
-        const response = await fetch(url, {
-            method: "DELETE",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-        });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to delete data source: ${response.status} ${errorText}`);
+            throw new ValidationError("Data source ID must be a non-empty string");
         }
+        await this.client["request"](`/v1/data-sources/${id}`, {}, { method: "DELETE" });
     }
     /**
      * Test a data source connection
@@ -245,21 +213,9 @@ export class DataSourcesResource {
      */
     async test(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Data source ID must be a non-empty string");
-        }
-        const url = `${this.client["baseUrl"]}/v1/data-sources/${id}/test`;
-        const response = await fetch(url, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-        });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to test data source: ${response.status} ${errorText}`);
+            throw new ValidationError("Data source ID must be a non-empty string");
         }
-        return response.json();
+        return this.client["request"](`/v1/data-sources/${id}/test`, {}, { method: "POST" });
     }
     /**
      * Get data source sync logs
@@ -283,7 +239,7 @@ export class DataSourcesResource {
      */
     async logs(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Data source ID must be a non-empty string");
+            throw new ValidationError("Data source ID must be a non-empty string");
         }
         const response = await this.client["request"](`/v1/data-sources/${id}/logs`, {});
         return Array.isArray(response) ? response : response.logs;
@@ -307,7 +263,7 @@ export class DataSourcesResource {
      */
     async health(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Data source ID must be a non-empty string");
+            throw new ValidationError("Data source ID must be a non-empty string");
         }
         return this.client["request"](`/v1/data-sources/${id}/health`, {});
     }
@@ -330,20 +286,8 @@ export class DataSourcesResource {
      */
     async rotateCredentials(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Data source ID must be a non-empty string");
-        }
-        const url = `${this.client["baseUrl"]}/v1/data-sources/${id}/rotate-credentials`;
-        const response = await fetch(url, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-        });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to rotate credentials: ${response.status} ${errorText}`);
+            throw new ValidationError("Data source ID must be a non-empty string");
         }
-        return response.json();
+        return this.client["request"](`/v1/data-sources/${id}/rotate-credentials`, {}, { method: "POST" });
     }
 }

package/dist/resources/diesel.d.ts

@@ -1,4 +1,4 @@
-import type { OilPriceAPI } from '../client.js';
+import type { OilPriceAPI } from "../client.js";
 /**
  * Diesel price data for a specific state or region
  */

package/dist/resources/diesel.js

@@ -1,3 +1,4 @@
+import { ValidationError } from "../errors.js";
 /**
  * Diesel Prices resource
  *
@@ -50,9 +51,9 @@ export class DieselResource {
      */
     async getPrice(state) {
         if (!state || state.length !== 2) {
-            throw new Error('State must be a 2-letter US state code (e.g., "CA", "TX")');
+            throw new ValidationError('State must be a 2-letter US state code (e.g., "CA", "TX")');
         }
-        const response = await this.client['request']('/v1/diesel-prices', { state: state.toUpperCase() });
+        const response = await this.client["request"]("/v1/diesel-prices", { state: state.toUpperCase() });
         return response.regional_average;
     }
     /**
@@ -98,47 +99,17 @@ export class DieselResource {
         const { lat, lng, radius = 8047 } = options;
         // Validate coordinates
         if (lat < -90 || lat > 90) {
-            throw new Error('Latitude must be between -90 and 90');
+            throw new ValidationError("Latitude must be between -90 and 90");
         }
         if (lng < -180 || lng > 180) {
-            throw new Error('Longitude must be between -180 and 180');
+            throw new ValidationError("Longitude must be between -180 and 180");
         }
         if (radius < 0 || radius > 50000) {
-            throw new Error('Radius must be between 0 and 50000 meters');
+            throw new ValidationError("Radius must be between 0 and 50000 meters");
         }
-        // Use POST request for stations endpoint
-        const response = await fetch(`${this.client['baseUrl']}/v1/diesel-prices/stations`, {
-            method: 'POST',
-            headers: {
-                'Authorization': `Bearer ${this.client['apiKey']}`,
-                'Content-Type': 'application/json',
-                'User-Agent': 'oilpriceapi-node/0.4.0',
-                'X-SDK-Language': 'javascript',
-                'X-SDK-Version': '0.4.0',
-                'X-Client-Type': 'sdk',
-            },
-            body: JSON.stringify({ lat, lng, radius }),
+        return this.client["request"]("/v1/diesel-prices/stations", {}, {
+            method: "POST",
+            body: { lat, lng, radius },
         });
-        if (!response.ok) {
-            const errorBody = await response.text();
-            let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
-            try {
-                const errorJson = JSON.parse(errorBody);
-                errorMessage = errorJson.message || errorJson.error || errorMessage;
-            }
-            catch {
-                // Use default error message
-            }
-            // Handle specific status codes
-            if (response.status === 403) {
-                throw new Error(`Diesel station queries not available on your plan. ${errorMessage}`);
-            }
-            if (response.status === 429) {
-                throw new Error(`Diesel station query limit exceeded. ${errorMessage}`);
-            }
-            throw new Error(errorMessage);
-        }
-        const data = await response.json();
-        return data;
     }
 }

package/dist/resources/drilling.js

@@ -4,6 +4,7 @@
  * Access US onshore drilling activity data including rig counts, well permits,
  * frac spreads, DUC wells, completions, and production trends by basin.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Drilling Intelligence Resource
  *
@@ -257,7 +258,7 @@ export class DrillingIntelligenceResource {
      */
     async basin(name) {
         if (!name || typeof name !== "string") {
-            throw new Error("Basin name must be a non-empty string");
+            throw new ValidationError("Basin name must be a non-empty string");
         }
         return this.client["request"](`/v1/drilling-intelligence/basin/${name}`, {});
     }

package/dist/resources/ei/drilling-productivity.js

@@ -4,6 +4,7 @@
  * Access EIA Drilling Productivity Report data including new well production,
  * legacy decline rates, and DUC well inventories by basin.
  */
+import { ValidationError } from "../../errors.js";
 /**
  * EI Drilling Productivity Resource
  *
@@ -44,7 +45,7 @@ export class EIDrillingProductivityResource {
      */
     async get(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Record ID must be a non-empty string");
+            throw new ValidationError("Record ID must be a non-empty string");
         }
         return this.client["request"](`/v1/ei/drilling_productivities/${id}`, {});
     }

package/dist/resources/ei/forecasts.js

@@ -3,6 +3,7 @@
  *
  * Access EIA and IEA price and production forecasts with historical accuracy metrics.
  */
+import { ValidationError } from "../../errors.js";
 /**
  * EI Forecasts Resource
  *
@@ -42,7 +43,7 @@ export class EIForecastsResource {
      */
     async get(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Record ID must be a non-empty string");
+            throw new ValidationError("Record ID must be a non-empty string");
         }
         return this.client["request"](`/v1/ei/forecasts/${id}`, {});
     }

package/dist/resources/ei/frac-focus.js

@@ -4,6 +4,7 @@
  * Access hydraulic fracturing disclosure data including chemicals, operators,
  * and well-level information from the FracFocus registry.
  */
+import { ValidationError } from "../../errors.js";
 /**
  * EI FracFocus Resource
  *
@@ -53,7 +54,7 @@ export class EIFracFocusResource {
      */
     async get(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Record ID must be a non-empty string");
+            throw new ValidationError("Record ID must be a non-empty string");
         }
         return this.client["request"](`/v1/ei/frac-focus/${id}`, {});
     }
@@ -129,7 +130,7 @@ export class EIFracFocusResource {
      */
     async chemicals(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Disclosure ID must be a non-empty string");
+            throw new ValidationError("Disclosure ID must be a non-empty string");
         }
         const response = await this.client["request"](`/v1/ei/frac-focus/${id}/chemicals`, {});
         return Array.isArray(response) ? response : response.chemicals;
@@ -142,7 +143,7 @@ export class EIFracFocusResource {
      */
     async forWell(apiNumber) {
         if (!apiNumber || typeof apiNumber !== "string") {
-            throw new Error("API number must be a non-empty string");
+            throw new ValidationError("API number must be a non-empty string");
         }
         const response = await this.client["request"](`/v1/ei/frac-focus/for-well/${apiNumber}`, {});
         return Array.isArray(response) ? response : response.data;

package/dist/resources/ei/index.js

@@ -11,6 +11,7 @@ import { EIDrillingProductivityResource } from "./drilling-productivity.js";
 import { EIForecastsResource } from "./forecasts.js";
 import { EIWellPermitsResource } from "./well-permits.js";
 import { EIFracFocusResource } from "./frac-focus.js";
+import { ValidationError } from "../../errors.js";
 /**
  * Energy Intelligence Resource
  *
@@ -79,7 +80,7 @@ export class EnergyIntelligenceResource {
      */
     async wellTimeline(apiNumber) {
         if (!apiNumber || typeof apiNumber !== "string") {
-            throw new Error("API number must be a non-empty string");
+            throw new ValidationError("API number must be a non-empty string");
         }
         return this.client["request"](`/v1/ei/wells/${apiNumber}/timeline`, {});
     }

package/dist/resources/ei/oil-inventories.js

@@ -4,6 +4,7 @@
  * Access EIA crude oil inventory data including total US stocks, Cushing levels,
  * and regional breakdowns.
  */
+import { ValidationError } from "../../errors.js";
 /**
  * EI Oil Inventories Resource
  *
@@ -43,7 +44,7 @@ export class EIOilInventoriesResource {
      */
     async get(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Record ID must be a non-empty string");
+            throw new ValidationError("Record ID must be a non-empty string");
         }
         return this.client["request"](`/v1/ei/oil_inventories/${id}`, {});
     }

package/dist/resources/ei/opec-production.js

@@ -3,6 +3,7 @@
  *
  * Access OPEC crude oil production data by country with historical trends.
  */
+import { ValidationError } from "../../errors.js";
 /**
  * EI OPEC Production Resource
  *
@@ -42,7 +43,7 @@ export class EIOPECProductionResource {
      */
     async get(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Record ID must be a non-empty string");
+            throw new ValidationError("Record ID must be a non-empty string");
         }
         return this.client["request"](`/v1/ei/opec_productions/${id}`, {});
     }

package/dist/resources/ei/rig-counts.js

@@ -3,6 +3,7 @@
  *
  * Access Baker Hughes rig count data with basin, state, and historical breakdowns.
  */
+import { ValidationError } from "../../errors.js";
 /**
  * EI Rig Counts Resource
  *
@@ -46,7 +47,7 @@ export class EIRigCountsResource {
      */
     async get(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Record ID must be a non-empty string");
+            throw new ValidationError("Record ID must be a non-empty string");
         }
         return this.client["request"](`/v1/ei/rig_counts/${id}`, {});
     }

package/dist/resources/ei/well-permits.js

@@ -3,6 +3,7 @@
  *
  * Access oil and gas well permit data by state, operator, and formation.
  */
+import { ValidationError } from "../../errors.js";
 /**
  * EI Well Permits Resource
  *
@@ -48,7 +49,7 @@ export class EIWellPermitsResource {
      */
     async get(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Record ID must be a non-empty string");
+            throw new ValidationError("Record ID must be a non-empty string");
         }
         return this.client["request"](`/v1/ei/well-permits/${id}`, {});
     }

package/dist/resources/forecasts.js

@@ -4,6 +4,7 @@
  * Access official price forecasts from EIA, IEA, and other agencies including
  * monthly outlooks, accuracy metrics, and historical archives.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Forecasts Resource
  *
@@ -147,7 +148,7 @@ export class ForecastsResource {
      */
     async get(period, commodity) {
         if (!period || typeof period !== "string") {
-            throw new Error("Period must be a non-empty string");
+            throw new ValidationError("Period must be a non-empty string");
         }
         const params = {};
         if (commodity)

package/dist/resources/futures.js

@@ -4,6 +4,7 @@
  * Access futures contract data including latest prices, historical data,
  * OHLC, intraday, spreads, curves, and continuous contracts.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Futures Resource
  *
@@ -52,7 +53,7 @@ export class FuturesResource {
      */
     async latest(contract) {
         if (!contract || typeof contract !== "string") {
-            throw new Error("Contract symbol must be a non-empty string");
+            throw new ValidationError("Contract symbol must be a non-empty string");
         }
         return this.client["request"](`/v1/futures/${contract}`, {});
     }
@@ -77,7 +78,7 @@ export class FuturesResource {
      */
     async historical(contract, options) {
         if (!contract || typeof contract !== "string") {
-            throw new Error("Contract symbol must be a non-empty string");
+            throw new ValidationError("Contract symbol must be a non-empty string");
         }
         const params = {};
         if (options?.startDate)
@@ -108,7 +109,7 @@ export class FuturesResource {
      */
     async ohlc(contract, date) {
         if (!contract || typeof contract !== "string") {
-            throw new Error("Contract symbol must be a non-empty string");
+            throw new ValidationError("Contract symbol must be a non-empty string");
         }
         const params = {};
         if (date)
@@ -136,7 +137,7 @@ export class FuturesResource {
      */
     async intraday(contract) {
         if (!contract || typeof contract !== "string") {
-            throw new Error("Contract symbol must be a non-empty string");
+            throw new ValidationError("Contract symbol must be a non-empty string");
         }
         return this.client["request"](`/v1/futures/${contract}/intraday`, {});
     }
@@ -161,10 +162,10 @@ export class FuturesResource {
      */
     async spreads(contract1, contract2) {
         if (!contract1 || typeof contract1 !== "string") {
-            throw new Error("First contract symbol must be a non-empty string");
+            throw new ValidationError("First contract symbol must be a non-empty string");
         }
         if (!contract2 || typeof contract2 !== "string") {
-            throw new Error("Second contract symbol must be a non-empty string");
+            throw new ValidationError("Second contract symbol must be a non-empty string");
         }
         return this.client["request"]("/v1/futures/spreads", {
             contract1,
@@ -193,7 +194,7 @@ export class FuturesResource {
      */
     async curve(contract) {
         if (!contract || typeof contract !== "string") {
-            throw new Error("Contract symbol must be a non-empty string");
+            throw new ValidationError("Contract symbol must be a non-empty string");
         }
         return this.client["request"](`/v1/futures/${contract}/curve`, {});
     }
@@ -218,7 +219,7 @@ export class FuturesResource {
      */
     async continuous(contract, months) {
         if (!contract || typeof contract !== "string") {
-            throw new Error("Contract symbol must be a non-empty string");
+            throw new ValidationError("Contract symbol must be a non-empty string");
         }
         const params = {};
         if (months !== undefined)

package/dist/resources/storage.js

@@ -4,6 +4,7 @@
  * Access crude oil storage data including total US inventory, Cushing hub levels,
  * Strategic Petroleum Reserve (SPR), and regional breakdowns.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Storage Resource
  *
@@ -148,7 +149,7 @@ export class StorageResource {
      */
     async history(code, options) {
         if (!code || typeof code !== "string") {
-            throw new Error("Storage location code must be a non-empty string");
+            throw new ValidationError("Storage location code must be a non-empty string");
         }
         const params = {};
         if (options?.startDate)

package/dist/resources/webhooks.d.ts

@@ -287,4 +287,40 @@ export declare class WebhooksResource {
      * ```
      */
     events(id: string): Promise<WebhookEvent[]>;
+    /**
+     * Verify a webhook signature.
+     *
+     * Validates that a webhook payload was sent by OilPriceAPI by checking
+     * the HMAC-SHA256 signature. Uses constant-time comparison to prevent
+     * timing attacks.
+     *
+     * @param payload - Raw request body (string or Buffer)
+     * @param signature - Value of the X-OilPriceAPI-Signature header (e.g., "sha256=abc123...")
+     * @param secret - Your webhook signing secret
+     * @returns true if signature is valid
+     *
+     * @example
+     * ```typescript
+     * import express from 'express';
+     * import { OilPriceAPI } from 'oilpriceapi';
+     *
+     * const app = express();
+     * const client = new OilPriceAPI({ apiKey: 'your_key' });
+     *
+     * // Use raw body parser for webhook routes
+     * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+     *   const signature = req.headers['x-oilpriceapi-signature'] as string;
+     *   const isValid = client.webhooks.verifySignature(req.body, signature, 'your_secret');
+     *
+     *   if (!isValid) {
+     *     return res.status(401).send('Invalid signature');
+     *   }
+     *
+     *   const event = JSON.parse(req.body.toString());
+     *   console.log('Verified webhook:', event.type);
+     *   res.sendStatus(200);
+     * });
+     * ```
+     */
+    verifySignature(payload: string | Buffer, signature: string, secret: string): boolean;
 }