oilpriceapi 0.7.0 → 0.9.0

package/dist/cjs/resources/rig-counts.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * Rig Counts Resource
+ *
+ * Access Baker Hughes rig count data including current counts, historical trends,
+ * and breakdowns by basin, state, and rig type.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RigCountsResource = void 0;
+/**
+ * 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}`);
+ * ```
+ */
+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) {
+        // The controller filters via `has_scope :by_period, using: %i[from to], type: :hash`,
+        // i.e. it reads nested `by_period[from]` / `by_period[to]` query params — NOT
+        // flat `start_date` / `end_date` (which were silently ignored by earlier SDKs).
+        const params = {};
+        if (options?.startDate)
+            params["by_period[from]"] = options.startDate;
+        if (options?.endDate)
+            params["by_period[to]"] = 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", {});
+    }
+}
+exports.RigCountsResource = RigCountsResource;

package/dist/cjs/resources/spreads.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Spreads Resource
+ *
+ * Access oil & product spread analytics: crack spreads, basis spreads,
+ * curve-structure (contango/backwardation), refining margins, and physical
+ * premiums. Each spread type supports the latest value, full history, and an
+ * `all` listing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpreadsResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Spreads Resource
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Latest crack spread
+ * const crack = await client.spreads.crack();
+ * console.log(`Crack spread: ${crack.value} ${crack.unit}`);
+ *
+ * // Historical basis spreads
+ * const history = await client.spreads.historical('basis', {
+ *   startDate: '2024-01-01',
+ *   endDate: '2024-12-31',
+ * });
+ *
+ * // All margin spreads
+ * const all = await client.spreads.all('margin');
+ * ```
+ */
+class SpreadsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get the latest value for a spread type.
+     *
+     * @param type - Spread type slug.
+     * @returns Latest spread value.
+     * @throws {ValidationError} If the type is invalid.
+     */
+    async get(type) {
+        this.validateType(type);
+        return this.client["request"](`/v1/spreads/${type}`, {});
+    }
+    /**
+     * Get historical data for a spread type.
+     *
+     * @param type - Spread type slug.
+     * @param options - Optional date range filters.
+     * @returns Array of historical spread values.
+     */
+    async historical(type, options) {
+        this.validateType(type);
+        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/spreads/${type}/historical`, params);
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get all spread values for a spread type.
+     *
+     * @param type - Spread type slug.
+     * @returns Array of spread values.
+     */
+    async all(type) {
+        this.validateType(type);
+        const response = await this.client["request"](`/v1/spreads/${type}/all`, {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /** Latest crack spread. */
+    async crack() {
+        return this.get("crack");
+    }
+    /** Latest basis spread. */
+    async basis() {
+        return this.get("basis");
+    }
+    /** Latest curve-structure (contango / backwardation). */
+    async curveStructure() {
+        return this.get("curve-structure");
+    }
+    /** Latest refining margin. */
+    async margin() {
+        return this.get("margin");
+    }
+    /** Latest physical premium. */
+    async physicalPremium() {
+        return this.get("physical-premium");
+    }
+    validateType(type) {
+        if (!type || typeof type !== "string") {
+            throw new errors_js_1.ValidationError("Spread type must be a non-empty string");
+        }
+    }
+}
+exports.SpreadsResource = SpreadsResource;

package/dist/cjs/resources/storage.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Storage Resource
+ *
+ * Access crude oil storage data including total US inventory, Cushing hub levels,
+ * Strategic Petroleum Reserve (SPR), and regional breakdowns.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * 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}`);
+ * ```
+ */
+class StorageResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    async all() {
+        return this.client["request"]("/v1/storage", {});
+    }
+    /**
+     * 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}%`);
+     * ```
+     */
+    async cushing() {
+        return this.client["request"]("/v1/storage/cushing", {});
+    }
+    /**
+     * 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}`);
+     * ```
+     */
+    async spr() {
+        return this.client["request"]("/v1/storage/spr", {});
+    }
+    /**
+     * 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}`);
+     * ```
+     */
+    async regional(region) {
+        const params = {};
+        if (region)
+            params.region = region;
+        return this.client["request"]("/v1/storage/regional", params);
+    }
+    /**
+     * 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}`);
+     * });
+     * ```
+     */
+    async history(code, options) {
+        if (!code || typeof code !== "string") {
+            throw new errors_js_1.ValidationError("Storage location code must be a non-empty string");
+        }
+        const params = {};
+        if (options?.period)
+            params.period = options.period;
+        // Route is GET /v1/storage/history/:code (the :code segment comes AFTER
+        // `history`), and the controller reads a `period` token.
+        const response = await this.client["request"](`/v1/storage/history/${code}`, params);
+        return Array.isArray(response) ? response : response.data;
+    }
+}
+exports.StorageResource = StorageResource;