oilpriceapi 0.6.0 → 0.8.2

package/dist/resources/futures.js

@@ -0,0 +1,229 @@
+/**
+ * Futures Resource
+ *
+ * Access futures contract data including latest prices, historical data,
+ * OHLC, intraday, spreads, curves, and continuous contracts.
+ */
+import { ValidationError } from "../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}`);
+ * });
+ * ```
+ */
+export 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 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 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 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 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 ValidationError("First contract symbol must be a non-empty string");
+        }
+        if (!contract2 || typeof contract2 !== "string") {
+            throw new 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 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 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);
+    }
+}

package/dist/resources/rig-counts.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Rig Counts Resource
+ *
+ * Access Baker Hughes rig count data including current counts, historical trends,
+ * and breakdowns by basin, state, and rig type.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Rig count data
+ */
+export interface RigCountData {
+    /** Total rig count */
+    total: number;
+    /** Oil rigs */
+    oil?: number;
+    /** Gas rigs */
+    gas?: number;
+    /** Miscellaneous rigs */
+    misc?: number;
+    /** Breakdown by region/state */
+    breakdown?: Record<string, number>;
+    /** ISO timestamp when data was recorded */
+    timestamp: string;
+    /** Week-over-week change */
+    change?: number;
+    /** Year-over-year change */
+    year_over_year_change?: number;
+}
+/**
+ * Historical rig count data point
+ */
+export interface HistoricalRigCountData {
+    /** Date in YYYY-MM-DD format */
+    date: string;
+    /** Total rig count */
+    total: number;
+    /** Oil rigs */
+    oil?: number;
+    /** Gas rigs */
+    gas?: number;
+    /** Miscellaneous rigs */
+    misc?: number;
+}
+/**
+ * Options for historical rig count query
+ */
+export interface HistoricalRigCountOptions {
+    /** Start date in ISO 8601 format (YYYY-MM-DD) */
+    startDate?: string;
+    /** End date in ISO 8601 format (YYYY-MM-DD) */
+    endDate?: string;
+}
+/**
+ * Rig count trend data
+ */
+export interface RigCountTrend {
+    /** Time period (e.g., "week", "month", "quarter", "year") */
+    period: string;
+    /** Average rig count */
+    average: number;
+    /** Minimum rig count */
+    min: number;
+    /** Maximum rig count */
+    max: number;
+    /** Overall trend direction */
+    trend?: "up" | "down" | "flat";
+    /** Percentage change */
+    change_percent?: number;
+}
+/**
+ * Rig count summary
+ */
+export interface RigCountSummary {
+    /** Current total */
+    current: number;
+    /** Week-over-week change */
+    week_change: number;
+    /** Month-over-month change */
+    month_change: number;
+    /** Year-over-year change */
+    year_change: number;
+    /** Breakdown by category */
+    breakdown: {
+        oil: number;
+        gas: number;
+        misc?: number;
+    };
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Rig Counts Resource
+ *
+ * Access Baker Hughes rig count data including current counts, historical data,
+ * trends, and summaries.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest rig count
+ * const latest = await client.rigCounts.latest();
+ * console.log(`Total rigs: ${latest.total}`);
+ * console.log(`Oil: ${latest.oil}, Gas: ${latest.gas}`);
+ *
+ * // Get summary with changes
+ * const summary = await client.rigCounts.summary();
+ * console.log(`Week-over-week: ${summary.week_change}`);
+ * console.log(`Year-over-year: ${summary.year_change}`);
+ * ```
+ */
+export declare class RigCountsResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * Get latest rig count data
+     *
+     * Returns the most recent Baker Hughes rig count.
+     *
+     * @returns Latest rig count data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const latest = await client.rigCounts.latest();
+     * console.log(`Total rigs: ${latest.total}`);
+     * console.log(`Oil rigs: ${latest.oil}`);
+     * console.log(`Gas rigs: ${latest.gas}`);
+     * console.log(`Change: ${latest.change}`);
+     * ```
+     */
+    latest(): Promise<RigCountData>;
+    /**
+     * Get current rig count data
+     *
+     * Alias for latest(). Returns the most recent Baker Hughes rig count.
+     *
+     * @returns Current rig count data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const current = await client.rigCounts.current();
+     * console.log(`Total rigs: ${current.total}`);
+     * ```
+     */
+    current(): Promise<RigCountData>;
+    /**
+     * Get historical rig count data
+     *
+     * Returns time series of rig counts.
+     *
+     * @param options - Date range filters
+     * @returns Array of historical rig count data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const history = await client.rigCounts.historical({
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31'
+     * });
+     *
+     * history.forEach(point => {
+     *   console.log(`${point.date}: ${point.total} rigs (${point.oil} oil, ${point.gas} gas)`);
+     * });
+     * ```
+     */
+    historical(options?: HistoricalRigCountOptions): Promise<HistoricalRigCountData[]>;
+    /**
+     * Get rig count trend analysis
+     *
+     * Returns trend analysis for a specified time period.
+     *
+     * @param period - Time period (e.g., "week", "month", "quarter", "year")
+     * @returns Trend analysis data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const monthlyTrend = await client.rigCounts.trends('month');
+     * console.log(`Monthly average: ${monthlyTrend.average}`);
+     * console.log(`Trend: ${monthlyTrend.trend}`);
+     * console.log(`Change: ${monthlyTrend.change_percent}%`);
+     * ```
+     */
+    trends(period?: string): Promise<RigCountTrend>;
+    /**
+     * Get rig count summary
+     *
+     * Returns comprehensive summary including current count and changes
+     * across multiple time periods.
+     *
+     * @returns Rig count summary
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const summary = await client.rigCounts.summary();
+     * console.log(`Current: ${summary.current}`);
+     * console.log(`Week-over-week: ${summary.week_change}`);
+     * console.log(`Month-over-month: ${summary.month_change}`);
+     * console.log(`Year-over-year: ${summary.year_change}`);
+     * console.log(`Oil rigs: ${summary.breakdown.oil}`);
+     * console.log(`Gas rigs: ${summary.breakdown.gas}`);
+     * ```
+     */
+    summary(): Promise<RigCountSummary>;
+}

package/dist/resources/rig-counts.js

@@ -0,0 +1,157 @@
+/**
+ * Rig Counts Resource
+ *
+ * Access Baker Hughes rig count data including current counts, historical trends,
+ * and breakdowns by basin, state, and rig type.
+ */
+/**
+ * Rig Counts Resource
+ *
+ * Access Baker Hughes rig count data including current counts, historical data,
+ * trends, and summaries.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest rig count
+ * const latest = await client.rigCounts.latest();
+ * console.log(`Total rigs: ${latest.total}`);
+ * console.log(`Oil: ${latest.oil}, Gas: ${latest.gas}`);
+ *
+ * // Get summary with changes
+ * const summary = await client.rigCounts.summary();
+ * console.log(`Week-over-week: ${summary.week_change}`);
+ * console.log(`Year-over-year: ${summary.year_change}`);
+ * ```
+ */
+export class RigCountsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get latest rig count data
+     *
+     * Returns the most recent Baker Hughes rig count.
+     *
+     * @returns Latest rig count data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const latest = await client.rigCounts.latest();
+     * console.log(`Total rigs: ${latest.total}`);
+     * console.log(`Oil rigs: ${latest.oil}`);
+     * console.log(`Gas rigs: ${latest.gas}`);
+     * console.log(`Change: ${latest.change}`);
+     * ```
+     */
+    async latest() {
+        return this.client["request"]("/v1/rig-counts/latest", {});
+    }
+    /**
+     * Get current rig count data
+     *
+     * Alias for latest(). Returns the most recent Baker Hughes rig count.
+     *
+     * @returns Current rig count data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const current = await client.rigCounts.current();
+     * console.log(`Total rigs: ${current.total}`);
+     * ```
+     */
+    async current() {
+        return this.client["request"]("/v1/rig-counts/current", {});
+    }
+    /**
+     * Get historical rig count data
+     *
+     * Returns time series of rig counts.
+     *
+     * @param options - Date range filters
+     * @returns Array of historical rig count data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const history = await client.rigCounts.historical({
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31'
+     * });
+     *
+     * history.forEach(point => {
+     *   console.log(`${point.date}: ${point.total} rigs (${point.oil} oil, ${point.gas} gas)`);
+     * });
+     * ```
+     */
+    async historical(options) {
+        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/rig-counts/historical", params);
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get rig count trend analysis
+     *
+     * Returns trend analysis for a specified time period.
+     *
+     * @param period - Time period (e.g., "week", "month", "quarter", "year")
+     * @returns Trend analysis data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const monthlyTrend = await client.rigCounts.trends('month');
+     * console.log(`Monthly average: ${monthlyTrend.average}`);
+     * console.log(`Trend: ${monthlyTrend.trend}`);
+     * console.log(`Change: ${monthlyTrend.change_percent}%`);
+     * ```
+     */
+    async trends(period) {
+        const params = {};
+        if (period)
+            params.period = period;
+        return this.client["request"]("/v1/rig-counts/trends", params);
+    }
+    /**
+     * Get rig count summary
+     *
+     * Returns comprehensive summary including current count and changes
+     * across multiple time periods.
+     *
+     * @returns Rig count summary
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const summary = await client.rigCounts.summary();
+     * console.log(`Current: ${summary.current}`);
+     * console.log(`Week-over-week: ${summary.week_change}`);
+     * console.log(`Month-over-month: ${summary.month_change}`);
+     * console.log(`Year-over-year: ${summary.year_change}`);
+     * console.log(`Oil rigs: ${summary.breakdown.oil}`);
+     * console.log(`Gas rigs: ${summary.breakdown.gas}`);
+     * ```
+     */
+    async summary() {
+        return this.client["request"]("/v1/rig-counts/summary", {});
+    }
+}