oilpriceapi 0.6.0 → 0.8.2

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

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Energy Intelligence - Rig Counts Resource
+ *
+ * Access Baker Hughes rig count data with basin, state, and historical breakdowns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EIRigCountsResource = void 0;
+const errors_js_1 = require("../../errors.js");
+/**
+ * EI Rig Counts Resource
+ *
+ * Access Baker Hughes rig count data with comprehensive breakdowns.
+ *
+ * @example
+ * ```typescript
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest rig count
+ * const latest = await client.ei.rigCounts.latest();
+ * console.log(`Total rigs: ${latest.total_rigs}`);
+ *
+ * // Get by basin
+ * const basins = await client.ei.rigCounts.byBasin();
+ * basins.forEach(b => console.log(`${b.basin}: ${b.rig_count} rigs`));
+ * ```
+ */
+class EIRigCountsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all rig count records
+     *
+     * @returns Array of rig count records
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/ei/rig_counts", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get a specific rig count record
+     *
+     * @param id - Record ID
+     * @returns Rig count record
+     *
+     * @throws {NotFoundError} If record not found
+     */
+    async get(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Record ID must be a non-empty string");
+        }
+        return this.client["request"](`/v1/ei/rig_counts/${id}`, {});
+    }
+    /**
+     * Get latest rig count
+     *
+     * @returns Latest rig count data
+     */
+    async latest() {
+        return this.client["request"]("/v1/ei/rig_counts/latest", {});
+    }
+    /**
+     * Get rig counts by basin
+     *
+     * @returns Array of rig counts by basin
+     */
+    async byBasin() {
+        const response = await this.client["request"]("/v1/ei/rig_counts/by_basin", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get rig counts by state
+     *
+     * @returns Array of rig counts by state
+     */
+    async byState() {
+        const response = await this.client["request"]("/v1/ei/rig_counts/by_state", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get historical rig count data
+     *
+     * @returns Array of historical rig counts
+     */
+    async historical() {
+        const response = await this.client["request"]("/v1/ei/rig_counts/historical", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+}
+exports.EIRigCountsResource = EIRigCountsResource;

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

@@ -0,0 +1,124 @@
+"use strict";
+/**
+ * Energy Intelligence - Well Permits Resource
+ *
+ * Access oil and gas well permit data by state, operator, and formation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EIWellPermitsResource = void 0;
+const errors_js_1 = require("../../errors.js");
+/**
+ * EI Well Permits Resource
+ *
+ * Access oil and gas well permit data with detailed breakdowns.
+ *
+ * @example
+ * ```typescript
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest permits
+ * const latest = await client.ei.wellPermits.latest();
+ * console.log(`Permit: ${latest.permit_number} - ${latest.operator}`);
+ *
+ * // Get permits by state
+ * const states = await client.ei.wellPermits.byState();
+ * states.forEach(s => console.log(`${s.state}: ${s.permit_count} permits`));
+ *
+ * // Search permits
+ * const results = await client.ei.wellPermits.search({
+ *   state: 'Texas',
+ *   operator: 'ConocoPhillips'
+ * });
+ * ```
+ */
+class EIWellPermitsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all well permit records
+     *
+     * @returns Array of well permit records
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/ei/well-permits", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get a specific well permit record
+     *
+     * @param id - Record ID
+     * @returns Well permit record
+     */
+    async get(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Record ID must be a non-empty string");
+        }
+        return this.client["request"](`/v1/ei/well-permits/${id}`, {});
+    }
+    /**
+     * Get latest well permit
+     *
+     * @returns Latest well permit record
+     */
+    async latest() {
+        return this.client["request"]("/v1/ei/well-permits/latest", {});
+    }
+    /**
+     * Get well permit summary
+     *
+     * @returns Well permit summary statistics
+     */
+    async summary() {
+        return this.client["request"]("/v1/ei/well-permits/summary", {});
+    }
+    /**
+     * Get permits by state
+     *
+     * @returns Array of permits grouped by state
+     */
+    async byState() {
+        const response = await this.client["request"]("/v1/ei/well-permits/by-state", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get permits by operator
+     *
+     * @returns Array of permits grouped by operator
+     */
+    async byOperator() {
+        const response = await this.client["request"]("/v1/ei/well-permits/by-operator", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get permits by formation
+     *
+     * @returns Array of permits grouped by formation
+     */
+    async byFormation() {
+        const response = await this.client["request"]("/v1/ei/well-permits/by-formation", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Search well permits
+     *
+     * @param query - Search query parameters
+     * @returns Array of matching well permit records
+     */
+    async search(query) {
+        const params = {};
+        if (query.state)
+            params.state = query.state;
+        if (query.operator)
+            params.operator = query.operator;
+        if (query.formation)
+            params.formation = query.formation;
+        if (query.start_date)
+            params.start_date = query.start_date;
+        if (query.end_date)
+            params.end_date = query.end_date;
+        const response = await this.client["request"]("/v1/ei/well-permits/search", params);
+        return Array.isArray(response) ? response : response.data;
+    }
+}
+exports.EIWellPermitsResource = EIWellPermitsResource;

package/dist/cjs/resources/forecasts.js

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Forecasts Resource
+ *
+ * Access official price forecasts from EIA, IEA, and other agencies including
+ * monthly outlooks, accuracy metrics, and historical archives.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForecastsResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Forecasts Resource
+ *
+ * Access official price forecasts from government agencies and research
+ * organizations including EIA, IEA, and others.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get monthly forecasts
+ * const forecasts = await client.forecasts.monthly();
+ * forecasts.forEach(f => {
+ *   console.log(`${f.period}: $${f.forecast_price} (${f.source})`);
+ * });
+ *
+ * // Check forecast accuracy
+ * const accuracy = await client.forecasts.accuracy();
+ * console.log(`EIA MAPE: ${accuracy.mape}%`);
+ * ```
+ */
+class ForecastsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get monthly price forecasts
+     *
+     * Returns official monthly forecasts from EIA, IEA, and other agencies.
+     *
+     * @param commodity - Optional commodity code filter
+     * @returns Array of monthly forecasts
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * // Get all forecasts
+     * const allForecasts = await client.forecasts.monthly();
+     *
+     * // Get WTI forecasts only
+     * const wtiForecasts = await client.forecasts.monthly('WTI_USD');
+     *
+     * wtiForecasts.forEach(forecast => {
+     *   console.log(`${forecast.period}: $${forecast.forecast_price}`);
+     *   console.log(`  Range: $${forecast.lower_bound} - $${forecast.upper_bound}`);
+     *   console.log(`  Source: ${forecast.source}`);
+     * });
+     * ```
+     */
+    async monthly(commodity) {
+        const params = {};
+        if (commodity)
+            params.commodity = commodity;
+        const response = await this.client["request"]("/v1/forecasts/monthly", params);
+        return Array.isArray(response) ? response : response.forecasts;
+    }
+    /**
+     * Get forecast accuracy metrics
+     *
+     * Returns historical accuracy measurements for forecast sources.
+     *
+     * @returns Forecast accuracy data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const accuracy = await client.forecasts.accuracy();
+     * console.log(`Source: ${accuracy.source}`);
+     * console.log(`MAPE: ${accuracy.mape}%`);
+     * console.log(`RMSE: ${accuracy.rmse}`);
+     * console.log(`Sample size: ${accuracy.sample_size} forecasts`);
+     * ```
+     */
+    async accuracy() {
+        return this.client["request"]("/v1/forecasts/accuracy", {});
+    }
+    /**
+     * Get archived forecasts
+     *
+     * Returns historical forecasts with actual outcomes for accuracy analysis.
+     *
+     * @param year - Optional year filter
+     * @returns Array of archived forecasts
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * // Get all archived forecasts
+     * const archive = await client.forecasts.archive();
+     *
+     * // Get forecasts from specific year
+     * const archive2024 = await client.forecasts.archive(2024);
+     *
+     * archive2024.forEach(forecast => {
+     *   if (forecast.actual_price) {
+     *     console.log(`${forecast.year}-${forecast.month}:`);
+     *     console.log(`  Forecast: $${forecast.forecast_price}`);
+     *     console.log(`  Actual: $${forecast.actual_price}`);
+     *     console.log(`  Error: ${forecast.error}%`);
+     *   }
+     * });
+     * ```
+     */
+    async archive(year) {
+        const params = {};
+        if (year)
+            params.year = year.toString();
+        const response = await this.client["request"]("/v1/forecasts/archive", params);
+        return Array.isArray(response) ? response : response.forecasts;
+    }
+    /**
+     * Get forecast for a specific period
+     *
+     * @param period - Period identifier (e.g., "2024-03", "2024-Q2")
+     * @param commodity - Optional commodity code filter
+     * @returns Monthly forecast data
+     *
+     * @throws {NotFoundError} If period not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * // Get March 2024 forecast
+     * const march2024 = await client.forecasts.get('2024-03');
+     *
+     * // Get Q2 2024 WTI forecast
+     * const q2Wti = await client.forecasts.get('2024-Q2', 'WTI_USD');
+     *
+     * console.log(`Period: ${march2024.period}`);
+     * console.log(`Forecast: $${march2024.forecast_price}`);
+     * console.log(`Published: ${march2024.published_at}`);
+     * ```
+     */
+    async get(period, commodity) {
+        if (!period || typeof period !== "string") {
+            throw new errors_js_1.ValidationError("Period must be a non-empty string");
+        }
+        const params = {};
+        if (commodity)
+            params.commodity = commodity;
+        return this.client["request"](`/v1/forecasts/monthly/${period}`, params);
+    }
+}
+exports.ForecastsResource = ForecastsResource;

package/dist/cjs/resources/futures.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * Futures Resource
+ *
+ * Access futures contract data including latest prices, historical data,
+ * OHLC, intraday, spreads, curves, and continuous contracts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FuturesResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Futures Resource
+ *
+ * Access futures contract data including latest, historical, OHLC, intraday,
+ * spreads, curves, and continuous contracts.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest price
+ * const latest = await client.futures.latest('CL.1');
+ * console.log(`${latest.contract}: $${latest.price}`);
+ *
+ * // Get OHLC data
+ * const ohlc = await client.futures.ohlc('CL.1', '2024-01-15');
+ * console.log(`High: $${ohlc.high}, Low: $${ohlc.low}`);
+ *
+ * // Get futures curve
+ * const curve = await client.futures.curve('CL');
+ * curve.curve.forEach(point => {
+ *   console.log(`${point.months_out}mo: $${point.price}`);
+ * });
+ * ```
+ */
+class FuturesResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get latest price for a futures contract
+     *
+     * @param contract - Contract symbol (e.g., "CL.1", "BZ.2")
+     * @returns Latest futures price data
+     *
+     * @throws {NotFoundError} If contract not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const price = await client.futures.latest('CL.1');
+     * console.log(`WTI Front Month: $${price.price}`);
+     * ```
+     */
+    async latest(contract) {
+        if (!contract || typeof contract !== "string") {
+            throw new errors_js_1.ValidationError("Contract symbol must be a non-empty string");
+        }
+        return this.client["request"](`/v1/futures/${contract}`, {});
+    }
+    /**
+     * Get historical prices for a futures contract
+     *
+     * @param contract - Contract symbol (e.g., "CL.1", "BZ.2")
+     * @param options - Date range filters
+     * @returns Array of historical prices
+     *
+     * @throws {NotFoundError} If contract not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const history = await client.futures.historical('CL.1', {
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-01-31'
+     * });
+     * console.log(`${history.length} historical prices`);
+     * ```
+     */
+    async historical(contract, options) {
+        if (!contract || typeof contract !== "string") {
+            throw new errors_js_1.ValidationError("Contract symbol 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/futures/${contract}/historical`, params);
+        return Array.isArray(response) ? response : response.prices;
+    }
+    /**
+     * Get OHLC (Open, High, Low, Close) data for a futures contract
+     *
+     * @param contract - Contract symbol (e.g., "CL.1", "BZ.2")
+     * @param date - Optional date in YYYY-MM-DD format (defaults to latest)
+     * @returns OHLC data
+     *
+     * @throws {NotFoundError} If contract not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const ohlc = await client.futures.ohlc('CL.1', '2024-01-15');
+     * console.log(`Open: $${ohlc.open}`);
+     * console.log(`High: $${ohlc.high}`);
+     * console.log(`Low: $${ohlc.low}`);
+     * console.log(`Close: $${ohlc.close}`);
+     * ```
+     */
+    async ohlc(contract, date) {
+        if (!contract || typeof contract !== "string") {
+            throw new errors_js_1.ValidationError("Contract symbol must be a non-empty string");
+        }
+        const params = {};
+        if (date)
+            params.date = date;
+        return this.client["request"](`/v1/futures/${contract}/ohlc`, params);
+    }
+    /**
+     * Get intraday price data for a futures contract
+     *
+     * Returns price points throughout the trading day.
+     *
+     * @param contract - Contract symbol (e.g., "CL.1", "BZ.2")
+     * @returns Intraday price data
+     *
+     * @throws {NotFoundError} If contract not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const intraday = await client.futures.intraday('CL.1');
+     * intraday.prices.forEach(point => {
+     *   console.log(`${point.time}: $${point.price}`);
+     * });
+     * ```
+     */
+    async intraday(contract) {
+        if (!contract || typeof contract !== "string") {
+            throw new errors_js_1.ValidationError("Contract symbol must be a non-empty string");
+        }
+        return this.client["request"](`/v1/futures/${contract}/intraday`, {});
+    }
+    /**
+     * Get spread between two futures contracts
+     *
+     * Calculates the price difference between two contracts (contract1 - contract2).
+     *
+     * @param contract1 - First contract symbol
+     * @param contract2 - Second contract symbol
+     * @returns Spread data
+     *
+     * @throws {NotFoundError} If either contract not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * // Calculate spread between front month and second month
+     * const spread = await client.futures.spreads('CL.1', 'CL.2');
+     * console.log(`CL.1 - CL.2 spread: $${spread.spread}`);
+     * ```
+     */
+    async spreads(contract1, contract2) {
+        if (!contract1 || typeof contract1 !== "string") {
+            throw new errors_js_1.ValidationError("First contract symbol must be a non-empty string");
+        }
+        if (!contract2 || typeof contract2 !== "string") {
+            throw new errors_js_1.ValidationError("Second contract symbol must be a non-empty string");
+        }
+        return this.client["request"]("/v1/futures/spreads", {
+            contract1,
+            contract2,
+        });
+    }
+    /**
+     * Get futures curve for a contract
+     *
+     * Returns the forward curve showing prices across different expiration dates.
+     *
+     * @param contract - Base contract symbol (e.g., "CL", "BZ")
+     * @returns Futures curve data
+     *
+     * @throws {NotFoundError} If contract not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const curve = await client.futures.curve('CL');
+     * console.log('WTI Futures Curve:');
+     * curve.curve.forEach(point => {
+     *   console.log(`${point.months_out} months: $${point.price}`);
+     * });
+     * ```
+     */
+    async curve(contract) {
+        if (!contract || typeof contract !== "string") {
+            throw new errors_js_1.ValidationError("Contract symbol must be a non-empty string");
+        }
+        return this.client["request"](`/v1/futures/${contract}/curve`, {});
+    }
+    /**
+     * Get continuous futures contract data
+     *
+     * Returns a continuous time series by rolling contracts before expiration.
+     *
+     * @param contract - Base contract symbol (e.g., "CL", "BZ")
+     * @param months - Number of months for continuous contract (default: 1 for front month)
+     * @returns Continuous contract data
+     *
+     * @throws {NotFoundError} If contract not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * // Get continuous front month contract
+     * const continuous = await client.futures.continuous('CL', 1);
+     * console.log(`${continuous.prices.length} data points`);
+     * ```
+     */
+    async continuous(contract, months) {
+        if (!contract || typeof contract !== "string") {
+            throw new errors_js_1.ValidationError("Contract symbol must be a non-empty string");
+        }
+        const params = {};
+        if (months !== undefined)
+            params.months = months.toString();
+        return this.client["request"](`/v1/futures/${contract}/continuous`, params);
+    }
+}
+exports.FuturesResource = FuturesResource;