oilpriceapi 0.5.3 → 0.7.0

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", {});
+    }
+}

package/dist/resources/storage.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Storage Resource
+ *
+ * Access crude oil storage data including total US inventory, Cushing hub levels,
+ * Strategic Petroleum Reserve (SPR), and regional breakdowns.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Storage level data
+ */
+export interface StorageData {
+    /** Storage location code */
+    code: string;
+    /** Location name */
+    name?: string;
+    /** Current storage level */
+    level: number;
+    /** Unit of measurement (typically "thousand_barrels" or "million_barrels") */
+    unit: string;
+    /** ISO timestamp when data was recorded */
+    timestamp: string;
+    /** Change from previous period */
+    change?: number;
+    /** Percentage change */
+    change_percent?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Historical storage data point
+ */
+export interface HistoricalStorageData {
+    /** Date in YYYY-MM-DD format */
+    date: string;
+    /** Storage level */
+    level: number;
+    /** Unit of measurement */
+    unit: string;
+    /** Week-over-week change */
+    change?: number;
+}
+/**
+ * Options for historical storage query
+ */
+export interface HistoricalStorageOptions {
+    /** Start date in ISO 8601 format (YYYY-MM-DD) */
+    startDate?: string;
+    /** End date in ISO 8601 format (YYYY-MM-DD) */
+    endDate?: string;
+}
+/**
+ * Storage Resource
+ *
+ * Access crude oil storage data for US inventory levels, Cushing hub,
+ * Strategic Petroleum Reserve, and regional breakdowns.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get all storage data
+ * const storage = await client.storage.all();
+ * console.log(`Total US inventory: ${storage.level} ${storage.unit}`);
+ *
+ * // Get Cushing levels
+ * const cushing = await client.storage.cushing();
+ * console.log(`Cushing: ${cushing.level} ${cushing.unit}`);
+ *
+ * // Get SPR levels
+ * const spr = await client.storage.spr();
+ * console.log(`SPR: ${spr.level} ${spr.unit}`);
+ * ```
+ */
+export declare class StorageResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * Get all current storage levels
+     *
+     * Returns total US commercial crude oil inventory.
+     *
+     * @returns Current storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const storage = await client.storage.all();
+     * console.log(`Total inventory: ${storage.level} ${storage.unit}`);
+     * if (storage.change) {
+     *   console.log(`Change: ${storage.change > 0 ? '+' : ''}${storage.change}`);
+     * }
+     * ```
+     */
+    all(): Promise<StorageData>;
+    /**
+     * Get Cushing, OK storage levels
+     *
+     * Returns current inventory at Cushing, Oklahoma - the key delivery point
+     * for WTI crude oil futures.
+     *
+     * @returns Cushing storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const cushing = await client.storage.cushing();
+     * console.log(`Cushing inventory: ${cushing.level} ${cushing.unit}`);
+     * console.log(`Week-over-week change: ${cushing.change_percent}%`);
+     * ```
+     */
+    cushing(): Promise<StorageData>;
+    /**
+     * Get Strategic Petroleum Reserve (SPR) levels
+     *
+     * Returns current US Strategic Petroleum Reserve inventory.
+     *
+     * @returns SPR storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const spr = await client.storage.spr();
+     * console.log(`SPR inventory: ${spr.level} ${spr.unit}`);
+     * ```
+     */
+    spr(): Promise<StorageData>;
+    /**
+     * Get regional storage breakdown
+     *
+     * Returns storage levels by region (PADD districts) or a specific region.
+     *
+     * @param region - Optional region code (e.g., "PADD1", "PADD2", "PADD3")
+     * @returns Regional storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * // Get all regions
+     * const regions = await client.storage.regional();
+     *
+     * // Get specific region (Gulf Coast)
+     * const gulfCoast = await client.storage.regional('PADD3');
+     * console.log(`PADD 3 (Gulf Coast): ${gulfCoast.level} ${gulfCoast.unit}`);
+     * ```
+     */
+    regional(region?: string): Promise<StorageData | StorageData[]>;
+    /**
+     * Get historical storage data
+     *
+     * Returns time series of storage levels for a specific location.
+     *
+     * @param code - Storage location code (e.g., "US", "CUSHING", "SPR")
+     * @param options - Date range filters
+     * @returns Array of historical storage data
+     *
+     * @throws {NotFoundError} If location code not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const history = await client.storage.history('CUSHING', {
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31'
+     * });
+     *
+     * history.forEach(point => {
+     *   console.log(`${point.date}: ${point.level} ${point.unit}`);
+     * });
+     * ```
+     */
+    history(code: string, options?: HistoricalStorageOptions): Promise<HistoricalStorageData[]>;
+}