oilpriceapi 0.8.2 → 0.9.1

package/dist/resources/futures.js

@@ -5,6 +5,163 @@
  * OHLC, intraday, spreads, curves, and continuous contracts.
  */
 import { ValidationError } from "../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();
+ * ```
+ */
+export const 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.
+ */
+export const FUTURES_FAMILY_SLUGS = {
+    [FUTURES_CONTRACTS.BRENT]: "ice-brent", // BZ
+    [FUTURES_CONTRACTS.WTI]: "ice-wti", // CL
+    [FUTURES_CONTRACTS.GASOIL]: "ice-gasoil", // G
+    QS: "ice-gasoil", // ICE Gasoil also trades under the QS ticker prefix
+    [FUTURES_CONTRACTS.NATURAL_GAS]: "natural-gas", // NG
+    [FUTURES_CONTRACTS.TTF_GAS]: "ttf-gas", // TTF
+    [FUTURES_CONTRACTS.LNG_JKM]: "lng-jkm", // JKM
+    [FUTURES_CONTRACTS.EUA_CARBON]: "eua-carbon", // EUA
+    [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.
+ */
+export function resolveFuturesFamilySlug(codeOrSlug) {
+    const trimmed = codeOrSlug.trim();
+    // Direct code match (case-insensitive — codes are upper-case).
+    const byCode = FUTURES_FAMILY_SLUGS[trimmed.toUpperCase()];
+    if (byCode)
+        return byCode;
+    // Already a valid family slug?
+    const lower = trimmed.toLowerCase();
+    const isSlug = Object.values(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();
+ * ```
+ */
+export 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`, {});
+    }
+}
 /**
  * Futures Resource
  *
@@ -17,16 +174,13 @@ import { ValidationError } from "../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}`);
  * });
@@ -37,25 +191,42 @@ export 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 ValidationError("Contract symbol must be a non-empty string");
         }
-        return this.client["request"](`/v1/futures/${contract}`, {});
+        const slug = resolveFuturesFamilySlug(contract);
+        if (!slug) {
+            throw new 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
@@ -226,4 +397,59 @@ export 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 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");
+    }
 }

package/dist/resources/indicators.d.ts

@@ -0,0 +1,170 @@
+/**
+ * Indicators Resource
+ *
+ * Access derived market indicators and signals: fuel-switching economics,
+ * price context, storage analytics, market annotations, CFTC positioning, and
+ * congressional energy-sector trades.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Supported indicator types.
+ */
+export type IndicatorType = "fuel-switching" | "price-context" | "storage-analytics" | "annotations" | "cftc-positioning" | "congressional-trades";
+/**
+ * Fuel-switching economics indicator.
+ */
+export interface FuelSwitchingIndicator {
+    /** Switching ratio or breakeven value */
+    value: number;
+    /** Whether switching is economical */
+    economical?: boolean;
+    /** From fuel (e.g., "gas") */
+    from_fuel?: string;
+    /** To fuel (e.g., "oil") */
+    to_fuel?: string;
+    /** Unit */
+    unit?: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Price-context indicator (where the current price sits historically).
+ */
+export interface PriceContextIndicator {
+    /** Commodity code */
+    commodity?: string;
+    /** Current price */
+    price: number;
+    /** Percentile vs trailing window */
+    percentile?: number;
+    /** 52-week high */
+    high_52w?: number;
+    /** 52-week low */
+    low_52w?: number;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Storage-analytics indicator.
+ */
+export interface StorageAnalyticsIndicator {
+    /** Storage level */
+    level: number;
+    /** Capacity utilization percentage */
+    capacity_percent?: number;
+    /** Days of cover */
+    days_of_cover?: number;
+    /** Z-score vs 5-year average */
+    zscore?: number;
+    /** Unit */
+    unit?: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Market annotation (notable event marker).
+ */
+export interface AnnotationIndicator {
+    /** Annotation ID */
+    id?: string;
+    /** Title */
+    title: string;
+    /** Description */
+    description?: string;
+    /** Category (e.g., "geopolitical", "supply", "demand") */
+    category?: string;
+    /** Event date */
+    date: string;
+    /** Related commodity */
+    commodity?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * CFTC positioning indicator (Commitment of Traders).
+ */
+export interface CFTCPositioningIndicator {
+    /** Market / commodity */
+    market?: string;
+    /** Managed-money long contracts */
+    managed_money_long?: number;
+    /** Managed-money short contracts */
+    managed_money_short?: number;
+    /** Net positioning */
+    net_position?: number;
+    /** Report date */
+    report_date: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Congressional trade indicator (energy-sector disclosures).
+ */
+export interface CongressionalTradeIndicator {
+    /** Representative or senator name */
+    member?: string;
+    /** Ticker traded */
+    ticker?: string;
+    /** Transaction type ("buy" / "sell") */
+    transaction_type?: string;
+    /** Amount range */
+    amount_range?: string;
+    /** Transaction date */
+    transaction_date: string;
+    /** Disclosure date */
+    disclosure_date?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * 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();
+ * ```
+ */
+export declare class IndicatorsResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * 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.
+     */
+    get<T = unknown>(type: IndicatorType): Promise<T>;
+    /** Fuel-switching economics indicator. */
+    fuelSwitching(): Promise<FuelSwitchingIndicator>;
+    /** Price-context indicator. */
+    priceContext(): Promise<PriceContextIndicator>;
+    /** Storage-analytics indicator. */
+    storageAnalytics(): Promise<StorageAnalyticsIndicator>;
+    /** Market annotations. */
+    annotations(): Promise<AnnotationIndicator[]>;
+    /** CFTC positioning (Commitment of Traders) indicators. */
+    cftcPositioning(): Promise<CFTCPositioningIndicator[]>;
+    /** Congressional energy-sector trade indicators. */
+    congressionalTrades(): Promise<CongressionalTradeIndicator[]>;
+}

package/dist/resources/indicators.js

@@ -0,0 +1,75 @@
+/**
+ * Indicators Resource
+ *
+ * Access derived market indicators and signals: fuel-switching economics,
+ * price context, storage analytics, market annotations, CFTC positioning, and
+ * congressional energy-sector trades.
+ */
+import { ValidationError } from "../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();
+ * ```
+ */
+export 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 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;
+    }
+}

package/dist/resources/raw.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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);
+ * ```
+ */
+import type { OilPriceAPI, APIResponse } from "../client.js";
+import type { Price, LatestPricesOptions, HistoricalPricesOptions, Commodity, CommoditiesResponse, CategoriesResponse } from "../types.js";
+/**
+ * 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.
+ */
+export declare class RawResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * 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');
+     * ```
+     */
+    get<T = unknown>(endpoint: string, params?: Record<string, string>): Promise<APIResponse<T>>;
+    /**
+     * 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' });
+     * ```
+     */
+    getLatestPrices(options?: LatestPricesOptions): Promise<APIResponse<Price[]>>;
+    /**
+     * 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',
+     * });
+     * ```
+     */
+    getHistoricalPrices(options?: HistoricalPricesOptions): Promise<APIResponse<Price[]>>;
+    /**
+     * Commodities metadata with raw HTTP status and headers.
+     *
+     * @returns Commodities response with HTTP status and headers.
+     */
+    getCommodities(): Promise<APIResponse<CommoditiesResponse>>;
+    /**
+     * Commodity categories with raw HTTP status and headers.
+     *
+     * @returns Categories response with HTTP status and headers.
+     */
+    getCommodityCategories(): Promise<APIResponse<CategoriesResponse>>;
+    /**
+     * 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.
+     */
+    getCommodity(code: string): Promise<APIResponse<Commodity>>;
+}