oilpriceapi 0.7.0 → 0.8.2

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

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * Rig Counts Resource
+ *
+ * Access Baker Hughes rig count data including current counts, historical trends,
+ * and breakdowns by basin, state, and rig type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RigCountsResource = void 0;
+/**
+ * Rig Counts Resource
+ *
+ * Access Baker Hughes rig count data including current counts, historical data,
+ * trends, and summaries.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest rig count
+ * const latest = await client.rigCounts.latest();
+ * console.log(`Total rigs: ${latest.total}`);
+ * console.log(`Oil: ${latest.oil}, Gas: ${latest.gas}`);
+ *
+ * // Get summary with changes
+ * const summary = await client.rigCounts.summary();
+ * console.log(`Week-over-week: ${summary.week_change}`);
+ * console.log(`Year-over-year: ${summary.year_change}`);
+ * ```
+ */
+class RigCountsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get latest rig count data
+     *
+     * Returns the most recent Baker Hughes rig count.
+     *
+     * @returns Latest rig count data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const latest = await client.rigCounts.latest();
+     * console.log(`Total rigs: ${latest.total}`);
+     * console.log(`Oil rigs: ${latest.oil}`);
+     * console.log(`Gas rigs: ${latest.gas}`);
+     * console.log(`Change: ${latest.change}`);
+     * ```
+     */
+    async latest() {
+        return this.client["request"]("/v1/rig-counts/latest", {});
+    }
+    /**
+     * Get current rig count data
+     *
+     * Alias for latest(). Returns the most recent Baker Hughes rig count.
+     *
+     * @returns Current rig count data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const current = await client.rigCounts.current();
+     * console.log(`Total rigs: ${current.total}`);
+     * ```
+     */
+    async current() {
+        return this.client["request"]("/v1/rig-counts/current", {});
+    }
+    /**
+     * Get historical rig count data
+     *
+     * Returns time series of rig counts.
+     *
+     * @param options - Date range filters
+     * @returns Array of historical rig count data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const history = await client.rigCounts.historical({
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31'
+     * });
+     *
+     * history.forEach(point => {
+     *   console.log(`${point.date}: ${point.total} rigs (${point.oil} oil, ${point.gas} gas)`);
+     * });
+     * ```
+     */
+    async historical(options) {
+        const params = {};
+        if (options?.startDate)
+            params.start_date = options.startDate;
+        if (options?.endDate)
+            params.end_date = options.endDate;
+        const response = await this.client["request"]("/v1/rig-counts/historical", params);
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get rig count trend analysis
+     *
+     * Returns trend analysis for a specified time period.
+     *
+     * @param period - Time period (e.g., "week", "month", "quarter", "year")
+     * @returns Trend analysis data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const monthlyTrend = await client.rigCounts.trends('month');
+     * console.log(`Monthly average: ${monthlyTrend.average}`);
+     * console.log(`Trend: ${monthlyTrend.trend}`);
+     * console.log(`Change: ${monthlyTrend.change_percent}%`);
+     * ```
+     */
+    async trends(period) {
+        const params = {};
+        if (period)
+            params.period = period;
+        return this.client["request"]("/v1/rig-counts/trends", params);
+    }
+    /**
+     * Get rig count summary
+     *
+     * Returns comprehensive summary including current count and changes
+     * across multiple time periods.
+     *
+     * @returns Rig count summary
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const summary = await client.rigCounts.summary();
+     * console.log(`Current: ${summary.current}`);
+     * console.log(`Week-over-week: ${summary.week_change}`);
+     * console.log(`Month-over-month: ${summary.month_change}`);
+     * console.log(`Year-over-year: ${summary.year_change}`);
+     * console.log(`Oil rigs: ${summary.breakdown.oil}`);
+     * console.log(`Gas rigs: ${summary.breakdown.gas}`);
+     * ```
+     */
+    async summary() {
+        return this.client["request"]("/v1/rig-counts/summary", {});
+    }
+}
+exports.RigCountsResource = RigCountsResource;

package/dist/cjs/resources/storage.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Storage Resource
+ *
+ * Access crude oil storage data including total US inventory, Cushing hub levels,
+ * Strategic Petroleum Reserve (SPR), and regional breakdowns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Storage Resource
+ *
+ * Access crude oil storage data for US inventory levels, Cushing hub,
+ * Strategic Petroleum Reserve, and regional breakdowns.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get all storage data
+ * const storage = await client.storage.all();
+ * console.log(`Total US inventory: ${storage.level} ${storage.unit}`);
+ *
+ * // Get Cushing levels
+ * const cushing = await client.storage.cushing();
+ * console.log(`Cushing: ${cushing.level} ${cushing.unit}`);
+ *
+ * // Get SPR levels
+ * const spr = await client.storage.spr();
+ * console.log(`SPR: ${spr.level} ${spr.unit}`);
+ * ```
+ */
+class StorageResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get all current storage levels
+     *
+     * Returns total US commercial crude oil inventory.
+     *
+     * @returns Current storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const storage = await client.storage.all();
+     * console.log(`Total inventory: ${storage.level} ${storage.unit}`);
+     * if (storage.change) {
+     *   console.log(`Change: ${storage.change > 0 ? '+' : ''}${storage.change}`);
+     * }
+     * ```
+     */
+    async all() {
+        return this.client["request"]("/v1/storage", {});
+    }
+    /**
+     * Get Cushing, OK storage levels
+     *
+     * Returns current inventory at Cushing, Oklahoma - the key delivery point
+     * for WTI crude oil futures.
+     *
+     * @returns Cushing storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const cushing = await client.storage.cushing();
+     * console.log(`Cushing inventory: ${cushing.level} ${cushing.unit}`);
+     * console.log(`Week-over-week change: ${cushing.change_percent}%`);
+     * ```
+     */
+    async cushing() {
+        return this.client["request"]("/v1/storage/cushing", {});
+    }
+    /**
+     * Get Strategic Petroleum Reserve (SPR) levels
+     *
+     * Returns current US Strategic Petroleum Reserve inventory.
+     *
+     * @returns SPR storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const spr = await client.storage.spr();
+     * console.log(`SPR inventory: ${spr.level} ${spr.unit}`);
+     * ```
+     */
+    async spr() {
+        return this.client["request"]("/v1/storage/spr", {});
+    }
+    /**
+     * Get regional storage breakdown
+     *
+     * Returns storage levels by region (PADD districts) or a specific region.
+     *
+     * @param region - Optional region code (e.g., "PADD1", "PADD2", "PADD3")
+     * @returns Regional storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * // Get all regions
+     * const regions = await client.storage.regional();
+     *
+     * // Get specific region (Gulf Coast)
+     * const gulfCoast = await client.storage.regional('PADD3');
+     * console.log(`PADD 3 (Gulf Coast): ${gulfCoast.level} ${gulfCoast.unit}`);
+     * ```
+     */
+    async regional(region) {
+        const params = {};
+        if (region)
+            params.region = region;
+        return this.client["request"]("/v1/storage/regional", params);
+    }
+    /**
+     * Get historical storage data
+     *
+     * Returns time series of storage levels for a specific location.
+     *
+     * @param code - Storage location code (e.g., "US", "CUSHING", "SPR")
+     * @param options - Date range filters
+     * @returns Array of historical storage data
+     *
+     * @throws {NotFoundError} If location code not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const history = await client.storage.history('CUSHING', {
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31'
+     * });
+     *
+     * history.forEach(point => {
+     *   console.log(`${point.date}: ${point.level} ${point.unit}`);
+     * });
+     * ```
+     */
+    async history(code, options) {
+        if (!code || typeof code !== "string") {
+            throw new errors_js_1.ValidationError("Storage location code must be a non-empty string");
+        }
+        const params = {};
+        if (options?.startDate)
+            params.start_date = options.startDate;
+        if (options?.endDate)
+            params.end_date = options.endDate;
+        const response = await this.client["request"](`/v1/storage/${code}/history`, params);
+        return Array.isArray(response) ? response : response.data;
+    }
+}
+exports.StorageResource = StorageResource;

package/dist/cjs/resources/webhooks.js

@@ -0,0 +1,294 @@
+"use strict";
+/**
+ * Webhooks Resource
+ *
+ * Manage webhook endpoints for real-time event notifications.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhooksResource = void 0;
+const errors_js_1 = require("../errors.js");
+const index_js_1 = require("../index.js");
+/**
+ * Webhooks Resource
+ *
+ * Manage webhook endpoints for real-time notifications about price changes,
+ * alerts, and other events.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Create a webhook
+ * const webhook = await client.webhooks.create({
+ *   name: 'Price Updates',
+ *   url: 'https://myapp.com/webhooks/prices',
+ *   events: ['price.updated', 'alert.triggered'],
+ *   enabled: true
+ * });
+ *
+ * // Test the webhook
+ * const test = await client.webhooks.test(webhook.id);
+ * console.log(`Test result: ${test.success ? 'passed' : 'failed'}`);
+ *
+ * // List all webhooks
+ * const webhooks = await client.webhooks.list();
+ * webhooks.forEach(wh => {
+ *   console.log(`${wh.name}: ${wh.successful_deliveries} successful`);
+ * });
+ *
+ * // Update webhook
+ * await client.webhooks.update(webhook.id, {
+ *   enabled: false
+ * });
+ *
+ * // Delete webhook
+ * await client.webhooks.delete(webhook.id);
+ * ```
+ */
+class WebhooksResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all webhook endpoints
+     *
+     * @returns Array of webhook endpoints
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const webhooks = await client.webhooks.list();
+     * webhooks.forEach(wh => {
+     *   console.log(`${wh.name} (${wh.enabled ? 'enabled' : 'disabled'})`);
+     *   console.log(`  Events: ${wh.events.join(', ')}`);
+     * });
+     * ```
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/webhooks", {});
+        return Array.isArray(response) ? response : response.webhooks;
+    }
+    /**
+     * Get a specific webhook endpoint
+     *
+     * @param id - Webhook ID
+     * @returns Webhook endpoint details
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.get('webhook-id');
+     * console.log(`${webhook.name}: ${webhook.url}`);
+     * console.log(`Success rate: ${webhook.successful_deliveries}/${webhook.successful_deliveries + webhook.failed_deliveries}`);
+     * ```
+     */
+    async get(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Webhook ID must be a non-empty string");
+        }
+        const response = await this.client["request"](`/v1/webhooks/${id}`, {});
+        return "webhook" in response ? response.webhook : response;
+    }
+    /**
+     * Create a new webhook endpoint
+     *
+     * @param params - Webhook configuration
+     * @returns Created webhook endpoint
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.create({
+     *   name: 'Production Alerts',
+     *   url: 'https://api.myapp.com/webhooks',
+     *   events: ['alert.triggered', 'price.updated'],
+     *   secret: 'my-webhook-secret',
+     *   enabled: true
+     * });
+     * console.log(`Webhook created: ${webhook.id}`);
+     * ```
+     */
+    async create(params) {
+        if (!params.name || typeof params.name !== "string") {
+            throw new errors_js_1.ValidationError("Webhook name is required");
+        }
+        if (!params.url || !params.url.startsWith("https://")) {
+            throw new errors_js_1.ValidationError("Webhook URL must use HTTPS protocol");
+        }
+        if (!params.events || !Array.isArray(params.events) || params.events.length === 0) {
+            throw new errors_js_1.ValidationError("At least one event type is required");
+        }
+        const response = await this.client["request"]("/v1/webhooks", {}, {
+            method: "POST",
+            body: {
+                webhook: {
+                    name: params.name,
+                    url: params.url,
+                    events: params.events,
+                    enabled: params.enabled ?? true,
+                    secret: params.secret,
+                    metadata: params.metadata,
+                },
+            },
+        });
+        return "webhook" in response ? response.webhook : response;
+    }
+    /**
+     * Update a webhook endpoint
+     *
+     * @param id - Webhook ID
+     * @param params - Fields to update
+     * @returns Updated webhook endpoint
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * // Disable a webhook
+     * await client.webhooks.update(webhookId, { enabled: false });
+     *
+     * // Change events
+     * await client.webhooks.update(webhookId, {
+     *   events: ['alert.triggered']
+     * });
+     * ```
+     */
+    async update(id, params) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Webhook ID must be a non-empty string");
+        }
+        if (params.url !== undefined && !params.url.startsWith("https://")) {
+            throw new errors_js_1.ValidationError("Webhook URL must use HTTPS protocol");
+        }
+        if (params.events !== undefined &&
+            (!Array.isArray(params.events) || params.events.length === 0)) {
+            throw new errors_js_1.ValidationError("Events must be a non-empty array");
+        }
+        const response = await this.client["request"](`/v1/webhooks/${id}`, {}, {
+            method: "PATCH",
+            body: { webhook: params },
+        });
+        return "webhook" in response ? response.webhook : response;
+    }
+    /**
+     * Delete a webhook endpoint
+     *
+     * @param id - Webhook ID
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * await client.webhooks.delete(webhookId);
+     * console.log('Webhook deleted');
+     * ```
+     */
+    async delete(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Webhook ID must be a non-empty string");
+        }
+        await this.client["request"](`/v1/webhooks/${id}`, {}, { method: "DELETE" });
+    }
+    /**
+     * Test a webhook endpoint
+     *
+     * Sends a test payload to the webhook URL to verify it's reachable.
+     *
+     * @param id - Webhook ID
+     * @returns Test results
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const test = await client.webhooks.test(webhookId);
+     * console.log(`Test ${test.success ? 'passed' : 'failed'}`);
+     * console.log(`Response time: ${test.response_time_ms}ms`);
+     * if (!test.success) {
+     *   console.log(`Error: ${test.error}`);
+     * }
+     * ```
+     */
+    async test(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Webhook ID must be a non-empty string");
+        }
+        return this.client["request"](`/v1/webhooks/${id}/test`, {}, { method: "POST" });
+    }
+    /**
+     * Get webhook event history
+     *
+     * Returns recent delivery events for a webhook.
+     *
+     * @param id - Webhook ID
+     * @returns Array of webhook events
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const events = await client.webhooks.events(webhookId);
+     * events.forEach(event => {
+     *   console.log(`${event.event_type}: ${event.status} (${event.attempts} attempts)`);
+     * });
+     * ```
+     */
+    async events(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Webhook ID must be a non-empty string");
+        }
+        const response = await this.client["request"](`/v1/webhooks/${id}/events`, {});
+        return Array.isArray(response) ? response : response.events;
+    }
+    /**
+     * 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, signature, secret) {
+        return (0, index_js_1.verifyWebhookSignature)(payload, signature, secret);
+    }
+}
+exports.WebhooksResource = WebhooksResource;

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/version.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_NAME = exports.SDK_VERSION = void 0;
+exports.buildUserAgent = buildUserAgent;
+/**
+ * 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)
+ */
+exports.SDK_VERSION = "0.8.2";
+/**
+ * SDK identifier used in User-Agent and X-Api-Client headers
+ */
+exports.SDK_NAME = "oilpriceapi-node";
+/**
+ * Build the full User-Agent string
+ */
+function buildUserAgent() {
+    return `${exports.SDK_NAME}/${exports.SDK_VERSION} node/${process.version}`;
+}

package/dist/client.d.ts

@@ -105,7 +105,7 @@ export declare class OilPriceAPI {
      * Data sources resource (BYOS - Bring Your Own Source)
      */
     readonly dataSources: DataSourcesResource;
-    constructor(config: OilPriceAPIConfig);
+    constructor(config?: OilPriceAPIConfig);
     /**
      * Log debug messages if debug mode is enabled
      */
@@ -123,7 +123,9 @@ export declare class OilPriceAPI {
      */
     private isRetryable;
     /**
-     * Internal method to make HTTP requests with retry and timeout
+     * Internal method to make HTTP requests with retry and timeout.
+     * Supports all HTTP methods (GET, POST, PATCH, DELETE) with consistent
+     * retry logic, timeout handling, and typed error responses.
      */
     private request;
     /**
@@ -165,6 +167,35 @@ export declare class OilPriceAPI {
      * ```
      */
     getHistoricalPrices(options?: HistoricalPricesOptions): Promise<Price[]>;
+    /**
+     * Paginate through historical prices automatically.
+     *
+     * Returns an async generator that yields pages of prices, fetching
+     * the next page only when needed. Avoids loading all data into memory.
+     *
+     * @param options - Same options as getHistoricalPrices, plus perPage (default: 100)
+     *
+     * @example
+     * ```typescript
+     * // Iterate through all pages
+     * for await (const page of client.paginateHistoricalPrices({
+     *   commodity: 'BRENT_CRUDE_USD',
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31',
+     *   perPage: 100,
+     * })) {
+     *   console.log(`Got ${page.length} prices`);
+     *   // Process each page...
+     * }
+     *
+     * // Or collect all prices
+     * const allPrices: Price[] = [];
+     * for await (const page of client.paginateHistoricalPrices({ commodity: 'WTI_USD' })) {
+     *   allPrices.push(...page);
+     * }
+     * ```
+     */
+    paginateHistoricalPrices(options?: HistoricalPricesOptions): AsyncGenerator<Price[]>;
     /**
      * Get prices from your connected data sources (BYOS)
      *