oilpriceapi 0.6.0 → 0.8.2

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

package/dist/resources/futures.d.ts

@@ -0,0 +1,322 @@
+/**
+ * Futures Resource
+ *
+ * Access futures contract data including latest prices, historical data,
+ * OHLC, intraday, spreads, curves, and continuous contracts.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Futures contract price data
+ */
+export interface FuturesPrice {
+    /** Contract symbol */
+    contract: string;
+    /** Current price */
+    price: number;
+    /** Formatted price string */
+    formatted?: string;
+    /** Currency code */
+    currency: string;
+    /** Contract expiration date */
+    expiration?: string;
+    /** ISO timestamp when price was recorded */
+    timestamp: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Historical futures price data
+ */
+export interface HistoricalFuturesPrice {
+    /** Contract symbol */
+    contract: string;
+    /** Price */
+    price: number;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Volume */
+    volume?: number;
+    /** Open interest */
+    open_interest?: number;
+}
+/**
+ * Options for historical futures query
+ */
+export interface HistoricalFuturesOptions {
+    /** Start date in ISO 8601 format (YYYY-MM-DD) */
+    startDate?: string;
+    /** End date in ISO 8601 format (YYYY-MM-DD) */
+    endDate?: string;
+}
+/**
+ * OHLC (Open, High, Low, Close) data for a futures contract
+ */
+export interface FuturesOHLC {
+    /** Contract symbol */
+    contract: string;
+    /** Date for this OHLC data */
+    date: string;
+    /** Opening price */
+    open: number;
+    /** Highest price */
+    high: number;
+    /** Lowest price */
+    low: number;
+    /** Closing price */
+    close: number;
+    /** Trading volume */
+    volume?: number;
+    /** Open interest */
+    open_interest?: number;
+}
+/**
+ * Intraday price point
+ */
+export interface IntradayPrice {
+    /** Time of day (e.g., "09:30", "14:00") */
+    time: string;
+    /** Price at this time */
+    price: number;
+    /** Volume at this time */
+    volume?: number;
+}
+/**
+ * Intraday futures data
+ */
+export interface IntradayFuturesData {
+    /** Contract symbol */
+    contract: string;
+    /** Date for this intraday data */
+    date: string;
+    /** Array of intraday price points */
+    prices: IntradayPrice[];
+}
+/**
+ * Futures spread data
+ */
+export interface FuturesSpread {
+    /** First contract symbol */
+    contract1: string;
+    /** Second contract symbol */
+    contract2: string;
+    /** Spread value (contract1 - contract2) */
+    spread: number;
+    /** Percentage spread */
+    spread_percent?: number;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Futures curve point
+ */
+export interface FuturesCurvePoint {
+    /** Contract expiration date */
+    expiration: string;
+    /** Months until expiration */
+    months_out: number;
+    /** Price */
+    price: number;
+    /** Contract symbol */
+    contract?: string;
+}
+/**
+ * Futures curve data
+ */
+export interface FuturesCurveData {
+    /** Base contract */
+    contract: string;
+    /** ISO timestamp when curve was generated */
+    timestamp: string;
+    /** Array of curve points */
+    curve: FuturesCurvePoint[];
+}
+/**
+ * Continuous contract data point
+ */
+export interface ContinuousContractPrice {
+    /** Date */
+    date: string;
+    /** Price */
+    price: number;
+    /** Active contract at this date */
+    active_contract?: string;
+}
+/**
+ * Continuous futures contract data
+ */
+export interface ContinuousFuturesData {
+    /** Base contract */
+    contract: string;
+    /** Number of months for continuous contract */
+    months: number;
+    /** Array of continuous prices */
+    prices: ContinuousContractPrice[];
+}
+/**
+ * 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}`);
+ * });
+ * ```
+ */
+export declare class FuturesResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * 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}`);
+     * ```
+     */
+    latest(contract: string): Promise<FuturesPrice>;
+    /**
+     * 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`);
+     * ```
+     */
+    historical(contract: string, options?: HistoricalFuturesOptions): Promise<HistoricalFuturesPrice[]>;
+    /**
+     * 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}`);
+     * ```
+     */
+    ohlc(contract: string, date?: string): Promise<FuturesOHLC>;
+    /**
+     * 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}`);
+     * });
+     * ```
+     */
+    intraday(contract: string): Promise<IntradayFuturesData>;
+    /**
+     * 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}`);
+     * ```
+     */
+    spreads(contract1: string, contract2: string): Promise<FuturesSpread>;
+    /**
+     * 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}`);
+     * });
+     * ```
+     */
+    curve(contract: string): Promise<FuturesCurveData>;
+    /**
+     * 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`);
+     * ```
+     */
+    continuous(contract: string, months?: number): Promise<ContinuousFuturesData>;
+}