oilpriceapi 0.6.0 → 0.8.2

package/dist/resources/ei/forecasts.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Energy Intelligence - Forecasts Resource
+ *
+ * Access EIA and IEA price and production forecasts with historical accuracy metrics.
+ */
+import type { OilPriceAPI } from "../../client.js";
+/**
+ * Forecast record
+ */
+export interface ForecastRecord {
+    /** Record ID */
+    id: string;
+    /** Forecast source (e.g., "EIA", "IEA") */
+    source?: string;
+    /** Commodity or metric being forecasted */
+    commodity?: string;
+    /** Forecast value */
+    forecast_value: number;
+    /** Unit of measurement */
+    unit?: string;
+    /** Forecast period (e.g., "Q1 2025", "2025") */
+    period?: string;
+    /** Publication date */
+    published_date: string;
+    /** Target date */
+    target_date?: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Forecast summary
+ */
+export interface ForecastSummary {
+    /** Number of forecasts */
+    total_forecasts: number;
+    /** Latest forecast value */
+    latest_forecast?: number;
+    /** Average forecast */
+    average_forecast?: number;
+    /** As of date */
+    as_of_date: string;
+}
+/**
+ * Price forecast data
+ */
+export interface PriceForecast {
+    /** Commodity */
+    commodity: string;
+    /** Forecast source */
+    source: string;
+    /** Forecast price */
+    forecast_price: number;
+    /** Unit */
+    unit: string;
+    /** Target period */
+    period: string;
+    /** Published date */
+    published_date: string;
+}
+/**
+ * Production forecast data
+ */
+export interface ProductionForecast {
+    /** Region or country */
+    region: string;
+    /** Forecast source */
+    source: string;
+    /** Forecast production */
+    forecast_production: number;
+    /** Unit */
+    unit: string;
+    /** Target period */
+    period: string;
+    /** Published date */
+    published_date: string;
+}
+/**
+ * Historical forecast data point
+ */
+export interface HistoricalForecast {
+    /** Date */
+    date: string;
+    /** Forecast value */
+    forecast_value: number;
+    /** Actual value (if available) */
+    actual_value?: number;
+    /** Accuracy percentage */
+    accuracy_percent?: number;
+}
+/**
+ * Forecast comparison data
+ */
+export interface ForecastComparison {
+    /** Period */
+    period: string;
+    /** EIA forecast */
+    eia_forecast?: number;
+    /** IEA forecast */
+    iea_forecast?: number;
+    /** Actual value (if available) */
+    actual_value?: number;
+    /** Difference between forecasts */
+    difference?: number;
+}
+/**
+ * EI Forecasts Resource
+ *
+ * Access EIA and IEA price and production forecasts.
+ *
+ * @example
+ * ```typescript
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest forecasts
+ * const latest = await client.ei.forecasts.latest();
+ * console.log(`Latest forecast: ${latest.forecast_value} ${latest.unit}`);
+ *
+ * // Get price forecasts
+ * const prices = await client.ei.forecasts.prices();
+ * prices.forEach(p => console.log(`${p.commodity}: $${p.forecast_price} (${p.source})`));
+ * ```
+ */
+export declare class EIForecastsResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * List all forecast records
+     *
+     * @returns Array of forecast records
+     */
+    list(): Promise<ForecastRecord[]>;
+    /**
+     * Get a specific forecast record
+     *
+     * @param id - Record ID
+     * @returns Forecast record
+     */
+    get(id: string): Promise<ForecastRecord>;
+    /**
+     * Get latest forecast data
+     *
+     * @returns Latest forecast record
+     */
+    latest(): Promise<ForecastRecord>;
+    /**
+     * Get forecast summary
+     *
+     * @returns Forecast summary statistics
+     */
+    summary(): Promise<ForecastSummary>;
+    /**
+     * Get price forecasts
+     *
+     * @returns Array of price forecasts
+     */
+    prices(): Promise<PriceForecast[]>;
+    /**
+     * Get production forecasts
+     *
+     * @returns Array of production forecasts
+     */
+    production(): Promise<ProductionForecast[]>;
+    /**
+     * Get historical forecast data
+     *
+     * @returns Array of historical forecasts with accuracy
+     */
+    historical(): Promise<HistoricalForecast[]>;
+    /**
+     * Compare forecasts from different sources
+     *
+     * @returns Array of forecast comparisons
+     */
+    compare(): Promise<ForecastComparison[]>;
+}

package/dist/resources/ei/forecasts.js

@@ -0,0 +1,102 @@
+/**
+ * Energy Intelligence - Forecasts Resource
+ *
+ * Access EIA and IEA price and production forecasts with historical accuracy metrics.
+ */
+import { ValidationError } from "../../errors.js";
+/**
+ * EI Forecasts Resource
+ *
+ * Access EIA and IEA price and production forecasts.
+ *
+ * @example
+ * ```typescript
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest forecasts
+ * const latest = await client.ei.forecasts.latest();
+ * console.log(`Latest forecast: ${latest.forecast_value} ${latest.unit}`);
+ *
+ * // Get price forecasts
+ * const prices = await client.ei.forecasts.prices();
+ * prices.forEach(p => console.log(`${p.commodity}: $${p.forecast_price} (${p.source})`));
+ * ```
+ */
+export class EIForecastsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all forecast records
+     *
+     * @returns Array of forecast records
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/ei/forecasts", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get a specific forecast record
+     *
+     * @param id - Record ID
+     * @returns Forecast record
+     */
+    async get(id) {
+        if (!id || typeof id !== "string") {
+            throw new ValidationError("Record ID must be a non-empty string");
+        }
+        return this.client["request"](`/v1/ei/forecasts/${id}`, {});
+    }
+    /**
+     * Get latest forecast data
+     *
+     * @returns Latest forecast record
+     */
+    async latest() {
+        return this.client["request"]("/v1/ei/forecasts/latest", {});
+    }
+    /**
+     * Get forecast summary
+     *
+     * @returns Forecast summary statistics
+     */
+    async summary() {
+        return this.client["request"]("/v1/ei/forecasts/summary", {});
+    }
+    /**
+     * Get price forecasts
+     *
+     * @returns Array of price forecasts
+     */
+    async prices() {
+        const response = await this.client["request"]("/v1/ei/forecasts/prices", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get production forecasts
+     *
+     * @returns Array of production forecasts
+     */
+    async production() {
+        const response = await this.client["request"]("/v1/ei/forecasts/production", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get historical forecast data
+     *
+     * @returns Array of historical forecasts with accuracy
+     */
+    async historical() {
+        const response = await this.client["request"]("/v1/ei/forecasts/historical", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Compare forecasts from different sources
+     *
+     * @returns Array of forecast comparisons
+     */
+    async compare() {
+        const response = await this.client["request"]("/v1/ei/forecasts/compare", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+}

package/dist/resources/ei/frac-focus.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Energy Intelligence - FracFocus Resource
+ *
+ * Access hydraulic fracturing disclosure data including chemicals, operators,
+ * and well-level information from the FracFocus registry.
+ */
+import type { OilPriceAPI } from "../../client.js";
+/**
+ * FracFocus disclosure record
+ */
+export interface FracFocusRecord {
+    /** Record ID */
+    id: string;
+    /** API well number */
+    api_number: string;
+    /** State */
+    state: string;
+    /** County */
+    county?: string;
+    /** Operator name */
+    operator?: string;
+    /** Well name */
+    well_name?: string;
+    /** Job start date */
+    job_start_date?: string;
+    /** Job end date */
+    job_end_date?: string;
+    /** Total base water volume (gallons) */
+    total_base_water_volume?: number;
+    /** Total base non-water volume (gallons) */
+    total_base_non_water_volume?: number;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * FracFocus summary
+ */
+export interface FracFocusSummary {
+    /** Total disclosures */
+    total_disclosures: number;
+    /** Disclosures by state */
+    by_state?: Record<string, number>;
+    /** Disclosures by operator */
+    by_operator?: Record<string, number>;
+    /** As of date */
+    as_of_date: string;
+}
+/**
+ * Disclosures by state
+ */
+export interface DisclosuresByState {
+    /** State name */
+    state: string;
+    /** Disclosure count */
+    disclosure_count: number;
+    /** Date */
+    date: string;
+}
+/**
+ * Disclosures by operator
+ */
+export interface DisclosuresByOperator {
+    /** Operator name */
+    operator: string;
+    /** Disclosure count */
+    disclosure_count: number;
+    /** Percentage of total */
+    percentage?: number;
+    /** Date */
+    date: string;
+}
+/**
+ * Chemical usage data
+ */
+export interface ChemicalUsage {
+    /** Chemical name */
+    chemical_name: string;
+    /** CAS number */
+    cas_number?: string;
+    /** Usage count */
+    usage_count: number;
+    /** Percentage of total */
+    percentage?: number;
+}
+/**
+ * Chemical detail for a specific well
+ */
+export interface WellChemical {
+    /** Chemical name */
+    chemical_name: string;
+    /** CAS number */
+    cas_number?: string;
+    /** Purpose */
+    purpose?: string;
+    /** Ingredient concentration (%) */
+    concentration_percent?: number;
+    /** Mass used (lbs) */
+    mass_lbs?: number;
+}
+/**
+ * FracFocus search query
+ */
+export interface FracFocusSearchQuery {
+    /** State filter */
+    state?: string;
+    /** Operator filter */
+    operator?: string;
+    /** Chemical filter */
+    chemical?: string;
+    /** Start date */
+    start_date?: string;
+    /** End date */
+    end_date?: string;
+}
+/**
+ * EI FracFocus Resource
+ *
+ * Access hydraulic fracturing disclosure data from the FracFocus registry.
+ *
+ * @example
+ * ```typescript
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest disclosure
+ * const latest = await client.ei.fracFocus.latest();
+ * console.log(`Well: ${latest.well_name} (API: ${latest.api_number})`);
+ *
+ * // Get disclosures by state
+ * const states = await client.ei.fracFocus.byState();
+ * states.forEach(s => console.log(`${s.state}: ${s.disclosure_count} disclosures`));
+ *
+ * // Get chemicals for a specific well
+ * const chemicals = await client.ei.fracFocus.chemicals('42-123-12345');
+ * chemicals.forEach(c => console.log(`${c.chemical_name}: ${c.concentration_percent}%`));
+ *
+ * // Search disclosures
+ * const results = await client.ei.fracFocus.search({
+ *   state: 'Texas',
+ *   operator: 'EOG Resources'
+ * });
+ * ```
+ */
+export declare class EIFracFocusResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * List all FracFocus disclosure records
+     *
+     * @returns Array of disclosure records
+     */
+    list(): Promise<FracFocusRecord[]>;
+    /**
+     * Get a specific FracFocus disclosure record
+     *
+     * @param id - Record ID
+     * @returns Disclosure record
+     */
+    get(id: string): Promise<FracFocusRecord>;
+    /**
+     * Get latest FracFocus disclosure
+     *
+     * @returns Latest disclosure record
+     */
+    latest(): Promise<FracFocusRecord>;
+    /**
+     * Get FracFocus summary
+     *
+     * @returns Disclosure summary statistics
+     */
+    summary(): Promise<FracFocusSummary>;
+    /**
+     * Get disclosures by state
+     *
+     * @returns Array of disclosures grouped by state
+     */
+    byState(): Promise<DisclosuresByState[]>;
+    /**
+     * Get disclosures by operator
+     *
+     * @returns Array of disclosures grouped by operator
+     */
+    byOperator(): Promise<DisclosuresByOperator[]>;
+    /**
+     * Get chemical usage statistics
+     *
+     * @returns Array of chemicals used in fracturing
+     */
+    byChemical(): Promise<ChemicalUsage[]>;
+    /**
+     * Search FracFocus disclosures
+     *
+     * @param query - Search query parameters
+     * @returns Array of matching disclosure records
+     */
+    search(query: FracFocusSearchQuery): Promise<FracFocusRecord[]>;
+    /**
+     * Get chemicals used in a specific well
+     *
+     * @param id - Disclosure record ID
+     * @returns Array of chemicals used in the well
+     */
+    chemicals(id: string): Promise<WellChemical[]>;
+    /**
+     * Get FracFocus disclosures for a specific well by API number
+     *
+     * @param apiNumber - API well number (e.g., "42-123-12345")
+     * @returns Array of disclosure records for the well
+     */
+    forWell(apiNumber: string): Promise<FracFocusRecord[]>;
+}

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

@@ -0,0 +1,151 @@
+/**
+ * Energy Intelligence - FracFocus Resource
+ *
+ * Access hydraulic fracturing disclosure data including chemicals, operators,
+ * and well-level information from the FracFocus registry.
+ */
+import { ValidationError } from "../../errors.js";
+/**
+ * EI FracFocus Resource
+ *
+ * Access hydraulic fracturing disclosure data from the FracFocus registry.
+ *
+ * @example
+ * ```typescript
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest disclosure
+ * const latest = await client.ei.fracFocus.latest();
+ * console.log(`Well: ${latest.well_name} (API: ${latest.api_number})`);
+ *
+ * // Get disclosures by state
+ * const states = await client.ei.fracFocus.byState();
+ * states.forEach(s => console.log(`${s.state}: ${s.disclosure_count} disclosures`));
+ *
+ * // Get chemicals for a specific well
+ * const chemicals = await client.ei.fracFocus.chemicals('42-123-12345');
+ * chemicals.forEach(c => console.log(`${c.chemical_name}: ${c.concentration_percent}%`));
+ *
+ * // Search disclosures
+ * const results = await client.ei.fracFocus.search({
+ *   state: 'Texas',
+ *   operator: 'EOG Resources'
+ * });
+ * ```
+ */
+export class EIFracFocusResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all FracFocus disclosure records
+     *
+     * @returns Array of disclosure records
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/ei/frac-focus", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get a specific FracFocus disclosure record
+     *
+     * @param id - Record ID
+     * @returns Disclosure record
+     */
+    async get(id) {
+        if (!id || typeof id !== "string") {
+            throw new ValidationError("Record ID must be a non-empty string");
+        }
+        return this.client["request"](`/v1/ei/frac-focus/${id}`, {});
+    }
+    /**
+     * Get latest FracFocus disclosure
+     *
+     * @returns Latest disclosure record
+     */
+    async latest() {
+        return this.client["request"]("/v1/ei/frac-focus/latest", {});
+    }
+    /**
+     * Get FracFocus summary
+     *
+     * @returns Disclosure summary statistics
+     */
+    async summary() {
+        return this.client["request"]("/v1/ei/frac-focus/summary", {});
+    }
+    /**
+     * Get disclosures by state
+     *
+     * @returns Array of disclosures grouped by state
+     */
+    async byState() {
+        const response = await this.client["request"]("/v1/ei/frac-focus/by-state", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get disclosures by operator
+     *
+     * @returns Array of disclosures grouped by operator
+     */
+    async byOperator() {
+        const response = await this.client["request"]("/v1/ei/frac-focus/by-operator", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get chemical usage statistics
+     *
+     * @returns Array of chemicals used in fracturing
+     */
+    async byChemical() {
+        const response = await this.client["request"]("/v1/ei/frac-focus/by-chemical", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Search FracFocus disclosures
+     *
+     * @param query - Search query parameters
+     * @returns Array of matching disclosure records
+     */
+    async search(query) {
+        const params = {};
+        if (query.state)
+            params.state = query.state;
+        if (query.operator)
+            params.operator = query.operator;
+        if (query.chemical)
+            params.chemical = query.chemical;
+        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/frac-focus/search", params);
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get chemicals used in a specific well
+     *
+     * @param id - Disclosure record ID
+     * @returns Array of chemicals used in the well
+     */
+    async chemicals(id) {
+        if (!id || typeof id !== "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;
+    }
+    /**
+     * Get FracFocus disclosures for a specific well by API number
+     *
+     * @param apiNumber - API well number (e.g., "42-123-12345")
+     * @returns Array of disclosure records for the well
+     */
+    async forWell(apiNumber) {
+        if (!apiNumber || typeof apiNumber !== "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;
+    }
+}