oilpriceapi 0.7.0 → 0.9.0

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,136 @@
+"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.states)
+            params.states = query.states;
+        if (query.county)
+            params.county = query.county;
+        if (query.well_name)
+            params.well_name = query.well_name;
+        if (query.permit_type)
+            params.permit_type = query.permit_type;
+        if (query.well_type)
+            params.well_type = query.well_type;
+        if (query.address)
+            params.address = query.address;
+        if (query.latitude !== undefined)
+            params.latitude = query.latitude.toString();
+        if (query.longitude !== undefined)
+            params.longitude = query.longitude.toString();
+        if (query.radius_miles !== undefined)
+            params.radius_miles = query.radius_miles.toString();
+        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,168 @@
+"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() {
+        // Route is /v1/forecasts/monthly/accuracy (the bare /accuracy 404s).
+        return this.client["request"]("/v1/forecasts/monthly/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(options) {
+        // Route is /v1/forecasts/monthly/archive (the bare /archive 404s). The
+        // controller reads only `page` / `per_page` — it does NOT filter by year,
+        // so the previous `year` argument was silently ignored.
+        const params = {};
+        if (options?.page !== undefined)
+            params.page = options.page.toString();
+        if (options?.perPage !== undefined)
+            params.per_page = options.perPage.toString();
+        const response = await this.client["request"]("/v1/forecasts/monthly/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;