oilpriceapi 0.6.0 → 0.7.0

package/dist/resources/ei/well-permits.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Energy Intelligence - Well Permits Resource
+ *
+ * Access oil and gas well permit data by state, operator, and formation.
+ */
+import type { OilPriceAPI } from "../../client.js";
+/**
+ * Well permit record
+ */
+export interface WellPermitRecord {
+    /** Record ID */
+    id: string;
+    /** Permit number */
+    permit_number?: string;
+    /** State */
+    state: string;
+    /** County */
+    county?: string;
+    /** Operator name */
+    operator?: string;
+    /** Well name */
+    well_name?: string;
+    /** Formation/target */
+    formation?: string;
+    /** Well type (e.g., "oil", "gas", "injection") */
+    well_type?: string;
+    /** Permit issue date */
+    issue_date: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Well permit summary
+ */
+export interface WellPermitSummary {
+    /** Total permits */
+    total_permits: number;
+    /** Permits by state */
+    by_state?: Record<string, number>;
+    /** Permits by operator */
+    by_operator?: Record<string, number>;
+    /** As of date */
+    as_of_date: string;
+}
+/**
+ * Permits by state
+ */
+export interface PermitsByState {
+    /** State name */
+    state: string;
+    /** Permit count */
+    permit_count: number;
+    /** Change from previous period */
+    change?: number;
+    /** Date */
+    date: string;
+}
+/**
+ * Permits by operator
+ */
+export interface PermitsByOperator {
+    /** Operator name */
+    operator: string;
+    /** Permit count */
+    permit_count: number;
+    /** Percentage of total */
+    percentage?: number;
+    /** Date */
+    date: string;
+}
+/**
+ * Permits by formation
+ */
+export interface PermitsByFormation {
+    /** Formation name */
+    formation: string;
+    /** Permit count */
+    permit_count: number;
+    /** Percentage of total */
+    percentage?: number;
+    /** Date */
+    date: string;
+}
+/**
+ * Well permit search query
+ */
+export interface WellPermitSearchQuery {
+    /** State filter */
+    state?: string;
+    /** Operator filter */
+    operator?: string;
+    /** Formation filter */
+    formation?: string;
+    /** Start date */
+    start_date?: string;
+    /** End date */
+    end_date?: string;
+}
+/**
+ * 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'
+ * });
+ * ```
+ */
+export declare class EIWellPermitsResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * List all well permit records
+     *
+     * @returns Array of well permit records
+     */
+    list(): Promise<WellPermitRecord[]>;
+    /**
+     * Get a specific well permit record
+     *
+     * @param id - Record ID
+     * @returns Well permit record
+     */
+    get(id: string): Promise<WellPermitRecord>;
+    /**
+     * Get latest well permit
+     *
+     * @returns Latest well permit record
+     */
+    latest(): Promise<WellPermitRecord>;
+    /**
+     * Get well permit summary
+     *
+     * @returns Well permit summary statistics
+     */
+    summary(): Promise<WellPermitSummary>;
+    /**
+     * Get permits by state
+     *
+     * @returns Array of permits grouped by state
+     */
+    byState(): Promise<PermitsByState[]>;
+    /**
+     * Get permits by operator
+     *
+     * @returns Array of permits grouped by operator
+     */
+    byOperator(): Promise<PermitsByOperator[]>;
+    /**
+     * Get permits by formation
+     *
+     * @returns Array of permits grouped by formation
+     */
+    byFormation(): Promise<PermitsByFormation[]>;
+    /**
+     * Search well permits
+     *
+     * @param query - Search query parameters
+     * @returns Array of matching well permit records
+     */
+    search(query: WellPermitSearchQuery): Promise<WellPermitRecord[]>;
+}

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

@@ -0,0 +1,119 @@
+/**
+ * Energy Intelligence - Well Permits Resource
+ *
+ * Access oil and gas well permit data by state, operator, and formation.
+ */
+/**
+ * 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'
+ * });
+ * ```
+ */
+export 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 Error("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;
+    }
+}

package/dist/resources/forecasts.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Forecasts Resource
+ *
+ * Access official price forecasts from EIA, IEA, and other agencies including
+ * monthly outlooks, accuracy metrics, and historical archives.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Monthly forecast data
+ */
+export interface MonthlyForecast {
+    /** Forecast period (e.g., "2024-03", "2024-Q2") */
+    period: string;
+    /** Commodity code */
+    commodity: string;
+    /** Forecasted price */
+    forecast_price: number;
+    /** Lower bound of forecast range */
+    lower_bound?: number;
+    /** Upper bound of forecast range */
+    upper_bound?: number;
+    /** Forecast source (e.g., "EIA", "IEA") */
+    source: string;
+    /** ISO timestamp when forecast was published */
+    published_at: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Forecast accuracy metrics
+ */
+export interface ForecastAccuracy {
+    /** Commodity code */
+    commodity?: string;
+    /** Forecast source */
+    source: string;
+    /** Mean Absolute Percentage Error */
+    mape: number;
+    /** Root Mean Squared Error */
+    rmse: number;
+    /** Mean Error (bias) */
+    mean_error?: number;
+    /** Number of forecasts evaluated */
+    sample_size: number;
+    /** Time period evaluated */
+    period_evaluated: string;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Archived forecast data
+ */
+export interface ArchivedForecast {
+    /** Year of forecast */
+    year: number;
+    /** Month of forecast (1-12) */
+    month?: number;
+    /** Quarter of forecast (1-4) */
+    quarter?: number;
+    /** Commodity code */
+    commodity: string;
+    /** Forecasted price */
+    forecast_price: number;
+    /** Actual price (if available) */
+    actual_price?: number;
+    /** Forecast error */
+    error?: number;
+    /** Forecast source */
+    source: string;
+    /** ISO timestamp when forecast was published */
+    published_at: string;
+}
+/**
+ * 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}%`);
+ * ```
+ */
+export declare class ForecastsResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * 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}`);
+     * });
+     * ```
+     */
+    monthly(commodity?: string): Promise<MonthlyForecast[]>;
+    /**
+     * 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`);
+     * ```
+     */
+    accuracy(): Promise<ForecastAccuracy>;
+    /**
+     * 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}%`);
+     *   }
+     * });
+     * ```
+     */
+    archive(year?: number): Promise<ArchivedForecast[]>;
+    /**
+     * 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}`);
+     * ```
+     */
+    get(period: string, commodity?: string): Promise<MonthlyForecast>;
+}

package/dist/resources/forecasts.js

@@ -0,0 +1,157 @@
+/**
+ * Forecasts Resource
+ *
+ * Access official price forecasts from EIA, IEA, and other agencies including
+ * monthly outlooks, accuracy metrics, and historical archives.
+ */
+/**
+ * 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}%`);
+ * ```
+ */
+export 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 Error("Period must be a non-empty string");
+        }
+        const params = {};
+        if (commodity)
+            params.commodity = commodity;
+        return this.client["request"](`/v1/forecasts/monthly/${period}`, params);
+    }
+}