oilpriceapi 0.7.0 → 0.9.0

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>>;
+}

package/dist/resources/raw.js

@@ -0,0 +1,124 @@
+/**
+ * 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);
+ * ```
+ */
+/**
+ * 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 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}`, {});
+    }
+}

package/dist/resources/rig-counts.js

@@ -96,11 +96,14 @@ export 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/resources/spreads.d.ts

@@ -0,0 +1,121 @@
+/**
+ * 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.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Supported spread types.
+ *
+ * - `crack` — refining crack spread (e.g., 3:2:1)
+ * - `basis` — regional basis differential vs benchmark
+ * - `curve-structure` — contango / backwardation structure
+ * - `margin` — refining margin
+ * - `physical-premium` — physical-vs-paper premium
+ */
+export type SpreadType = "crack" | "basis" | "curve-structure" | "margin" | "physical-premium";
+/**
+ * A single spread data point.
+ */
+export interface SpreadValue {
+    /** Spread type slug */
+    type: string;
+    /** Spread name / label */
+    name?: string;
+    /** Spread value */
+    value: number;
+    /** Unit (e.g., "USD/bbl") */
+    unit?: string;
+    /** Region or market */
+    region?: string;
+    /** Benchmark or components */
+    components?: string[];
+    /** ISO timestamp */
+    timestamp: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Historical spread data point.
+ */
+export interface HistoricalSpreadValue {
+    /** ISO date */
+    date: string;
+    /** Spread value */
+    value: number;
+    /** Unit */
+    unit?: string;
+}
+/**
+ * Options for a historical spread query.
+ */
+export interface HistoricalSpreadOptions {
+    /** Start date (YYYY-MM-DD) */
+    startDate?: string;
+    /** End date (YYYY-MM-DD) */
+    endDate?: string;
+}
+/**
+ * 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');
+ * ```
+ */
+export declare class SpreadsResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * Get the latest value for a spread type.
+     *
+     * @param type - Spread type slug.
+     * @returns Latest spread value.
+     * @throws {ValidationError} If the type is invalid.
+     */
+    get(type: SpreadType): Promise<SpreadValue>;
+    /**
+     * Get historical data for a spread type.
+     *
+     * @param type - Spread type slug.
+     * @param options - Optional date range filters.
+     * @returns Array of historical spread values.
+     */
+    historical(type: SpreadType, options?: HistoricalSpreadOptions): Promise<HistoricalSpreadValue[]>;
+    /**
+     * Get all spread values for a spread type.
+     *
+     * @param type - Spread type slug.
+     * @returns Array of spread values.
+     */
+    all(type: SpreadType): Promise<SpreadValue[]>;
+    /** Latest crack spread. */
+    crack(): Promise<SpreadValue>;
+    /** Latest basis spread. */
+    basis(): Promise<SpreadValue>;
+    /** Latest curve-structure (contango / backwardation). */
+    curveStructure(): Promise<SpreadValue>;
+    /** Latest refining margin. */
+    margin(): Promise<SpreadValue>;
+    /** Latest physical premium. */
+    physicalPremium(): Promise<SpreadValue>;
+    private validateType;
+}