oilpriceapi 0.7.0 → 0.9.0

package/dist/cjs/resources/futures.js

@@ -0,0 +1,424 @@
+"use strict";
+/**
+ * Futures Resource
+ *
+ * Access futures contract data including latest prices, historical data,
+ * OHLC, intraday, spreads, curves, and continuous contracts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FuturesResource = exports.FuturesContractFamily = exports.FUTURES_FAMILY_SLUGS = exports.FUTURES_CONTRACTS = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Ergonomic contract codes for the most-requested futures families (issue #1).
+ *
+ * Use with the generic {@link FuturesResource} methods, or use the typed
+ * {@link FuturesResource.family} helper for direct access to a family's
+ * endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { FUTURES_CONTRACTS } from 'oilpriceapi';
+ *
+ * const brent = await client.futures.latest(FUTURES_CONTRACTS.BRENT); // "BZ"
+ * const gasoil = await client.futures.family('ice-gasoil').latest();
+ * ```
+ */
+exports.FUTURES_CONTRACTS = {
+    /** ICE Brent crude */
+    BRENT: "BZ",
+    /** NYMEX WTI crude */
+    WTI: "CL",
+    /** ICE Gasoil */
+    GASOIL: "G",
+    /** Henry Hub natural gas */
+    NATURAL_GAS: "NG",
+    /** TTF natural gas (Europe) */
+    TTF_GAS: "TTF",
+    /** LNG JKM (Asia) */
+    LNG_JKM: "JKM",
+    /** EU carbon allowance */
+    EUA_CARBON: "EUA",
+    /** UK carbon allowance */
+    UK_CARBON: "UKA",
+};
+/**
+ * Mapping of ergonomic contract codes to their API contract-family slugs.
+ *
+ * Lets you resolve a contract code (e.g., `"BZ"`) to the `/v1/futures/{slug}`
+ * path segment used by the typed family helpers.
+ */
+exports.FUTURES_FAMILY_SLUGS = {
+    [exports.FUTURES_CONTRACTS.BRENT]: "ice-brent",
+    [exports.FUTURES_CONTRACTS.WTI]: "ice-wti",
+    [exports.FUTURES_CONTRACTS.GASOIL]: "ice-gasoil",
+    [exports.FUTURES_CONTRACTS.NATURAL_GAS]: "natural-gas",
+    [exports.FUTURES_CONTRACTS.TTF_GAS]: "ttf-gas",
+    [exports.FUTURES_CONTRACTS.LNG_JKM]: "lng-jkm",
+    [exports.FUTURES_CONTRACTS.EUA_CARBON]: "eua-carbon",
+    [exports.FUTURES_CONTRACTS.UK_CARBON]: "uk-carbon",
+};
+/**
+ * Typed helper for a single futures contract family (e.g., ICE Brent, Gasoil).
+ *
+ * Provides ergonomic access to the family's endpoints without having to
+ * remember the URL slug. Obtain an instance via {@link FuturesResource.family},
+ * {@link FuturesResource.brent}, {@link FuturesResource.gasoil}, etc.
+ *
+ * @example
+ * ```typescript
+ * const gasoil = client.futures.gasoil();
+ * const latest = await gasoil.latest();
+ * const curve = await gasoil.curve();
+ * ```
+ */
+class FuturesContractFamily {
+    constructor(client, 
+    /** The contract-family slug used in the API path. */
+    slug) {
+        this.client = client;
+        this.slug = slug;
+    }
+    /**
+     * Get the latest price for this contract family.
+     */
+    async latest() {
+        return this.client["request"](`/v1/futures/${this.slug}/latest`, {});
+    }
+    /**
+     * Get historical prices for this contract family.
+     *
+     * @param options - Optional date range filters.
+     */
+    async historical(options) {
+        const params = {};
+        if (options?.startDate)
+            params.from = options.startDate;
+        if (options?.endDate)
+            params.to = options.endDate;
+        if (options?.interval)
+            params.interval = options.interval;
+        if (options?.contracts)
+            params.contracts = options.contracts;
+        const response = await this.client["request"](`/v1/futures/${this.slug}/historical`, params);
+        return Array.isArray(response) ? response : response.prices;
+    }
+    /**
+     * Get OHLC data for this contract family.
+     *
+     * @param options - `{ days, contract, interval }` (the API has no `date` param here).
+     */
+    async ohlc(options) {
+        const params = {};
+        if (options?.days !== undefined)
+            params.days = options.days.toString();
+        if (options?.contract)
+            params.contract = options.contract;
+        if (options?.interval)
+            params.interval = options.interval;
+        return this.client["request"](`/v1/futures/${this.slug}/ohlc`, params);
+    }
+    /**
+     * Get intraday price data for this contract family.
+     */
+    async intraday() {
+        return this.client["request"](`/v1/futures/${this.slug}/intraday`, {});
+    }
+    /**
+     * Get the spreads for this contract family.
+     */
+    async spreads() {
+        const response = await this.client["request"](`/v1/futures/${this.slug}/spreads`, {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get the forward curve for this contract family.
+     */
+    async curve() {
+        return this.client["request"](`/v1/futures/${this.slug}/curve`, {});
+    }
+    /**
+     * Get historical spread data for this contract family.
+     */
+    async spreadHistory() {
+        return this.client["request"](`/v1/futures/${this.slug}/spread-history`, {});
+    }
+}
+exports.FuturesContractFamily = FuturesContractFamily;
+/**
+ * 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}`);
+ * });
+ * ```
+ */
+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 errors_js_1.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 errors_js_1.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 errors_js_1.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 errors_js_1.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 errors_js_1.ValidationError("First contract symbol must be a non-empty string");
+        }
+        if (!contract2 || typeof contract2 !== "string") {
+            throw new errors_js_1.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 errors_js_1.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 errors_js_1.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);
+    }
+    /**
+     * Get a typed helper for a specific contract family (issue #1).
+     *
+     * Provides ergonomic access to the ICE Brent / WTI / Gasoil and gas/carbon
+     * family endpoints (`/latest`, `/historical`, `/ohlc`, `/intraday`,
+     * `/spreads`, `/curve`, `/spread-history`) without remembering the URL slug.
+     *
+     * @param slug - Contract family slug (e.g., `"ice-brent"`, `"ice-gasoil"`).
+     * @returns A {@link FuturesContractFamily} bound to the slug.
+     *
+     * @example
+     * ```typescript
+     * const brent = client.futures.family('ice-brent');
+     * const latest = await brent.latest();
+     * const curve = await brent.curve();
+     * ```
+     */
+    family(slug) {
+        if (!slug || typeof slug !== "string") {
+            throw new errors_js_1.ValidationError("Contract family slug must be a non-empty string");
+        }
+        return new FuturesContractFamily(this.client, slug);
+    }
+    /** ICE Brent crude futures family helper (issue #1). */
+    brent() {
+        return this.family("ice-brent");
+    }
+    /** ICE WTI crude futures family helper. */
+    wti() {
+        return this.family("ice-wti");
+    }
+    /** ICE Gasoil futures family helper (issue #1). */
+    gasoil() {
+        return this.family("ice-gasoil");
+    }
+    /** Henry Hub natural gas futures family helper. */
+    naturalGas() {
+        return this.family("natural-gas");
+    }
+    /** TTF natural gas (Europe) futures family helper. */
+    ttfGas() {
+        return this.family("ttf-gas");
+    }
+    /** LNG JKM (Asia) futures family helper. */
+    lngJkm() {
+        return this.family("lng-jkm");
+    }
+    /** EU carbon allowance (EUA) futures family helper. */
+    euaCarbon() {
+        return this.family("eua-carbon");
+    }
+    /** UK carbon allowance (UKA) futures family helper. */
+    ukCarbon() {
+        return this.family("uk-carbon");
+    }
+}
+exports.FuturesResource = FuturesResource;

package/dist/cjs/resources/indicators.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Indicators Resource
+ *
+ * Access derived market indicators and signals: fuel-switching economics,
+ * price context, storage analytics, market annotations, CFTC positioning, and
+ * congressional energy-sector trades.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndicatorsResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Indicators Resource
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Fuel-switching economics
+ * const fs = await client.indicators.fuelSwitching();
+ * console.log(`Switching economical: ${fs.economical}`);
+ *
+ * // CFTC positioning
+ * const cftc = await client.indicators.cftcPositioning();
+ * cftc.forEach(p => console.log(`${p.market}: net ${p.net_position}`));
+ *
+ * // Congressional trades
+ * const trades = await client.indicators.congressionalTrades();
+ * ```
+ */
+class IndicatorsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get an arbitrary indicator by type.
+     *
+     * @typeParam T - Expected response type.
+     * @param type - Indicator type slug.
+     * @returns The indicator data.
+     * @throws {ValidationError} If the type is invalid.
+     */
+    async get(type) {
+        if (!type || typeof type !== "string") {
+            throw new errors_js_1.ValidationError("Indicator type must be a non-empty string");
+        }
+        return this.client["request"](`/v1/indicators/${type}`, {});
+    }
+    /** Fuel-switching economics indicator. */
+    async fuelSwitching() {
+        return this.get("fuel-switching");
+    }
+    /** Price-context indicator. */
+    async priceContext() {
+        return this.get("price-context");
+    }
+    /** Storage-analytics indicator. */
+    async storageAnalytics() {
+        return this.get("storage-analytics");
+    }
+    /** Market annotations. */
+    async annotations() {
+        const response = await this.client["request"]("/v1/indicators/annotations", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /** CFTC positioning (Commitment of Traders) indicators. */
+    async cftcPositioning() {
+        const response = await this.client["request"]("/v1/indicators/cftc-positioning", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /** Congressional energy-sector trade indicators. */
+    async congressionalTrades() {
+        const response = await this.client["request"]("/v1/indicators/congressional-trades", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+}
+exports.IndicatorsResource = IndicatorsResource;

package/dist/cjs/resources/raw.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Raw Response Resource
+ *
+ * Provides opt-in access to the underlying HTTP status code and response
+ * headers alongside the parsed data. Mirrors the most commonly used top-level
+ * client methods. This is the #1 requested enhancement (issue #7).
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * const { data, status, headers } = await client.raw.getLatestPrices();
+ * console.log(`HTTP ${status}`);
+ * console.log(`Rate limit remaining: ${headers.get('x-ratelimit-remaining')}`);
+ * console.log(data[0].price);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RawResource = void 0;
+/**
+ * Raw Response Resource
+ *
+ * Each method returns an {@link APIResponse} with `{ data, status, headers }`
+ * instead of just the parsed data, so callers can inspect HTTP metadata such
+ * as rate-limit headers, caching headers, and the exact status code.
+ */
+class RawResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Make an arbitrary GET request and return data plus HTTP status and headers.
+     *
+     * Use this for endpoints without a dedicated raw helper.
+     *
+     * @typeParam T - Expected parsed response type.
+     * @param endpoint - API path beginning with `/` (e.g. `/v1/prices/latest`).
+     * @param params - Optional query parameters.
+     * @returns The parsed data along with the HTTP status code and headers.
+     *
+     * @example
+     * ```typescript
+     * const { data, status, headers } = await client.raw.get('/v1/futures/CL.1');
+     * ```
+     */
+    async get(endpoint, params) {
+        return this.client["requestRaw"](endpoint, params);
+    }
+    /**
+     * Latest prices with raw HTTP status and headers.
+     *
+     * @param options - Optional commodity filter.
+     * @returns Prices array with HTTP status and headers.
+     *
+     * @example
+     * ```typescript
+     * const { data, status, headers } = await client.raw.getLatestPrices({ commodity: 'WTI_USD' });
+     * ```
+     */
+    async getLatestPrices(options) {
+        const params = {};
+        if (options?.commodity) {
+            params.by_code = options.commodity;
+        }
+        return this.client["requestRaw"]("/v1/prices/latest", params);
+    }
+    /**
+     * Historical prices with raw HTTP status and headers.
+     *
+     * @param options - Time period and filter options.
+     * @returns Prices array with HTTP status and headers.
+     *
+     * @example
+     * ```typescript
+     * const { data, status, headers } = await client.raw.getHistoricalPrices({
+     *   period: 'past_week',
+     *   commodity: 'BRENT_CRUDE_USD',
+     * });
+     * ```
+     */
+    async getHistoricalPrices(options) {
+        const params = {};
+        if (options?.period)
+            params.period = options.period;
+        if (options?.commodity)
+            params.by_code = options.commodity;
+        if (options?.startDate)
+            params.start_date = options.startDate;
+        if (options?.endDate)
+            params.end_date = options.endDate;
+        if (options?.interval)
+            params.interval = options.interval;
+        if (options?.perPage !== undefined)
+            params.per_page = options.perPage.toString();
+        if (options?.page !== undefined)
+            params.page = options.page.toString();
+        return this.client["requestRaw"]("/v1/prices/past_year", params);
+    }
+    /**
+     * Commodities metadata with raw HTTP status and headers.
+     *
+     * @returns Commodities response with HTTP status and headers.
+     */
+    async getCommodities() {
+        return this.client["requestRaw"]("/v1/commodities", {});
+    }
+    /**
+     * Commodity categories with raw HTTP status and headers.
+     *
+     * @returns Categories response with HTTP status and headers.
+     */
+    async getCommodityCategories() {
+        return this.client["requestRaw"]("/v1/commodities/categories", {});
+    }
+    /**
+     * A single commodity's metadata with raw HTTP status and headers.
+     *
+     * @param code - Commodity code (e.g., "WTI_USD").
+     * @returns Commodity with HTTP status and headers.
+     */
+    async getCommodity(code) {
+        return this.client["requestRaw"](`/v1/commodities/${code}`, {});
+    }
+}
+exports.RawResource = RawResource;