oilpriceapi 0.8.2 → 0.9.1

package/dist/cjs/resources/futures.js

@@ -6,8 +6,167 @@
  * OHLC, intraday, spreads, curves, and continuous contracts.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FuturesResource = void 0;
+exports.FuturesResource = exports.FuturesContractFamily = exports.FUTURES_FAMILY_SLUGS = exports.FUTURES_CONTRACTS = void 0;
+exports.resolveFuturesFamilySlug = resolveFuturesFamilySlug;
 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", // BZ
+    [exports.FUTURES_CONTRACTS.WTI]: "ice-wti", // CL
+    [exports.FUTURES_CONTRACTS.GASOIL]: "ice-gasoil", // G
+    QS: "ice-gasoil", // ICE Gasoil also trades under the QS ticker prefix
+    [exports.FUTURES_CONTRACTS.NATURAL_GAS]: "natural-gas", // NG
+    [exports.FUTURES_CONTRACTS.TTF_GAS]: "ttf-gas", // TTF
+    [exports.FUTURES_CONTRACTS.LNG_JKM]: "lng-jkm", // JKM
+    [exports.FUTURES_CONTRACTS.EUA_CARBON]: "eua-carbon", // EUA
+    [exports.FUTURES_CONTRACTS.UK_CARBON]: "uk-carbon", // UKA
+};
+/**
+ * Resolve a futures contract code (e.g. `"BZ"`, `"QS"`) or an already-valid
+ * family slug (e.g. `"ice-brent"`) to its `/v1/futures/{slug}` path segment.
+ *
+ * Matching is case-insensitive for codes. Returns `null` if the input maps to
+ * neither a known code nor a known family slug.
+ */
+function resolveFuturesFamilySlug(codeOrSlug) {
+    const trimmed = codeOrSlug.trim();
+    // Direct code match (case-insensitive — codes are upper-case).
+    const byCode = exports.FUTURES_FAMILY_SLUGS[trimmed.toUpperCase()];
+    if (byCode)
+        return byCode;
+    // Already a valid family slug?
+    const lower = trimmed.toLowerCase();
+    const isSlug = Object.values(exports.FUTURES_FAMILY_SLUGS).includes(lower);
+    return isSlug ? lower : null;
+}
+/**
+ * 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.
+     *
+     * Latest is served from the bare slug path `GET /v1/futures/{slug}` —
+     * there is NO `/latest` suffix (that path 404s).
+     */
+    async latest() {
+        return this.client["request"](`/v1/futures/${this.slug}`, {});
+    }
+    /**
+     * 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
  *
@@ -20,16 +179,13 @@ const errors_js_1 = require("../errors.js");
  *
  * const client = new OilPriceAPI({ apiKey: 'your_key' });
  *
- * // Get latest price
- * const latest = await client.futures.latest('CL.1');
+ * // Get the latest curve by contract code (resolves to GET /v1/futures/ice-wti)
+ * const latest = await client.futures.latest('CL');
  * 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');
+ * // Typed family helpers are the most ergonomic option:
+ * const brent = await client.futures.brent().latest();
+ * const curve = await client.futures.brent().curve();
  * curve.curve.forEach(point => {
  *   console.log(`${point.months_out}mo: $${point.price}`);
  * });
@@ -40,25 +196,42 @@ class FuturesResource {
         this.client = client;
     }
     /**
-     * Get latest price for a futures contract
+     * Get the latest curve/quote for a futures contract family.
      *
-     * @param contract - Contract symbol (e.g., "CL.1", "BZ.2")
-     * @returns Latest futures price data
+     * Accepts an ergonomic contract code (e.g. `"BZ"`, `"CL"`, `"QS"`) or a
+     * family slug (e.g. `"ice-brent"`). The code is resolved to its family slug
+     * and the request is sent to `GET /v1/futures/{slug}` — the bare slug path,
+     * with NO `/latest` suffix (the suffixed path 404s).
      *
-     * @throws {NotFoundError} If contract not found
+     * Supported codes: BZ (Brent), CL (WTI), G/QS (Gasoil), NG (Natural Gas),
+     * TTF, JKM, EUA, UKA. Slugs: ice-brent, ice-wti, ice-gasoil, natural-gas,
+     * ttf-gas, lng-jkm, eua-carbon, uk-carbon.
+     *
+     * @param contract - Contract code (e.g. "BZ") or family slug (e.g. "ice-brent").
+     * @returns Latest futures price/curve data
+     *
+     * @throws {ValidationError} If the code/slug is empty or unrecognized.
      * @throws {OilPriceAPIError} If API request fails
      *
      * @example
      * ```typescript
-     * const price = await client.futures.latest('CL.1');
-     * console.log(`WTI Front Month: $${price.price}`);
+     * import { FUTURES_CONTRACTS } from 'oilpriceapi';
+     * const price = await client.futures.latest(FUTURES_CONTRACTS.BRENT); // "BZ"
+     * const wti = await client.futures.latest('ice-wti');
      * ```
      */
     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}`, {});
+        const slug = resolveFuturesFamilySlug(contract);
+        if (!slug) {
+            throw new errors_js_1.ValidationError(`Unknown futures contract "${contract}". Use a contract code ` +
+                `(BZ, CL, G, QS, NG, TTF, JKM, EUA, UKA) or a family slug ` +
+                `(ice-brent, ice-wti, ice-gasoil, natural-gas, ttf-gas, lng-jkm, ` +
+                `eua-carbon, uk-carbon).`);
+        }
+        return this.client["request"](`/v1/futures/${slug}`, {});
     }
     /**
      * Get historical prices for a futures contract
@@ -229,5 +402,60 @@ class FuturesResource {
             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;

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

@@ -99,11 +99,14 @@ class RigCountsResource {
      * ```
      */
     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.start_date = options.startDate;
+            params["by_period[from]"] = options.startDate;
         if (options?.endDate)
-            params.end_date = 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;
     }

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

@@ -155,11 +155,11 @@ class StorageResource {
             throw new errors_js_1.ValidationError("Storage location code 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/storage/${code}/history`, 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;
     }
 }