oilpriceapi 0.8.2 → 0.9.1

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

package/dist/resources/spreads.js

@@ -0,0 +1,101 @@
+/**
+ * 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 { ValidationError } from "../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');
+ * ```
+ */
+export 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 ValidationError("Spread type must be a non-empty string");
+        }
+    }
+}

package/dist/resources/storage.d.ts

@@ -43,10 +43,11 @@ export interface HistoricalStorageData {
  * Options for historical storage query
  */
 export interface HistoricalStorageOptions {
-    /** Start date in ISO 8601 format (YYYY-MM-DD) */
-    startDate?: string;
-    /** End date in ISO 8601 format (YYYY-MM-DD) */
-    endDate?: string;
+    /**
+     * Lookback period. The API reads a `period` token, one of
+     * '7d' | '30d' | '90d' (default) | '1y' | 'all' — not arbitrary date ranges.
+     */
+    period?: "7d" | "30d" | "90d" | "1y" | "all";
 }
 /**
  * Storage Resource

package/dist/resources/storage.js

@@ -152,11 +152,11 @@ export class StorageResource {
             throw new 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;
     }
 }

package/dist/resources/streaming.d.ts

@@ -0,0 +1,272 @@
+/**
+ * WebSocket Streaming Resource
+ *
+ * Real-time price streaming via the OilPriceAPI ActionCable endpoint
+ * (`wss://api.oilpriceapi.com/cable`).
+ *
+ * Streaming is a **Reservoir Mastery (Professional+)** feature. Connections
+ * authenticate with your API key and subscribe to the `EnergyPricesChannel`,
+ * which pushes an initial `welcome` snapshot followed by live `price_update`
+ * and (for drilling-tier accounts) `rig_count_update` messages.
+ *
+ * The implementation speaks the raw ActionCable JSON subprotocol over the
+ * `ws` package: it performs the `welcome` -> `subscribe` ->
+ * `confirm_subscription` handshake, answers server `ping` frames, and
+ * surfaces decoded channel messages as typed events. Auto-reconnect with
+ * exponential backoff keeps the stream alive across transient network drops.
+ *
+ * @example
+ * ```typescript
+ * const sub = client.stream.prices({}, (update) => {
+ *   console.log(update.prices.oil.wti?.original_price);
+ * });
+ *
+ * sub.on("rig_count_update", (m) => console.log(m.rig_count.region, m.rig_count.count));
+ * sub.on("error", (err) => console.error(err));
+ *
+ * // later
+ * sub.close();
+ * ```
+ */
+import { EventEmitter } from "node:events";
+import WebSocket from "ws";
+import type { OilPriceAPI } from "../client.js";
+/**
+ * The ActionCable channel exposed by the OilPriceAPI server.
+ *
+ * Confirmed from `app/channels/energy_prices_channel.rb`
+ * (`class EnergyPricesChannel`).
+ */
+export declare const ENERGY_PRICES_CHANNEL = "EnergyPricesChannel";
+/**
+ * A single normalized price point as broadcast by the server.
+ *
+ * Mirrors the shape produced by `BroadcastEnergyPricesJob#normalized_price_for_cached`
+ * and `EnergyPricesChannel#normalize_price`.
+ */
+export interface StreamedPrice {
+    /** Price converted to the common base unit (USD / MMBtu). */
+    normalized_price: number | null;
+    /** Original price in its native unit/currency. */
+    original_price: number | null;
+    /** Native unit (e.g. `"barrel_oil"`, `"mmbtu"`). */
+    original_unit: string;
+    /** Native currency (e.g. `"USD"`, `"GBP"`, `"EUR"`). */
+    original_currency: string;
+    /** ISO-8601 timestamp of the underlying price record. */
+    timestamp: string;
+    /** 24h absolute change (present on the initial `welcome` snapshot). */
+    change_24h?: number;
+    /** 24h percent change (present on the initial `welcome` snapshot). */
+    change_24h_percent?: number;
+}
+/**
+ * The `prices` map carried by `welcome` and `price_update` messages.
+ */
+export interface StreamedPriceMap {
+    oil: {
+        brent: StreamedPrice | null;
+        wti: StreamedPrice | null;
+    };
+    natural_gas: {
+        uk: StreamedPrice | null;
+        us: StreamedPrice | null;
+        eu: StreamedPrice | null;
+    };
+}
+/**
+ * Live `price_update` broadcast (the most common streamed message).
+ */
+export interface PriceUpdateMessage {
+    type: "price_update";
+    timestamp: string;
+    base_currency: string;
+    base_unit: string;
+    prices: StreamedPriceMap;
+}
+/**
+ * Initial snapshot transmitted immediately on subscription confirmation.
+ *
+ * Note: the server uses `type: "welcome"` for this *channel* message. It is
+ * distinct from the ActionCable transport-level `welcome` frame, which the
+ * client consumes internally and never surfaces.
+ */
+export interface WelcomeMessage {
+    type: "welcome";
+    data: {
+        timestamp?: string;
+        base_currency?: string;
+        base_unit?: string;
+        prices?: StreamedPriceMap;
+        /** Present only for drilling-tier accounts. */
+        drilling_intelligence?: Record<string, unknown>;
+        /** Present when the initial snapshot could not be built. */
+        error?: string;
+    };
+}
+/**
+ * Rig-count update broadcast (drilling / Reservoir Mastery accounts).
+ */
+export interface RigCountUpdateMessage {
+    type: "rig_count_update";
+    timestamp: string;
+    rig_count: {
+        code: string;
+        region: string;
+        count: number;
+        source: string;
+        updated_at: string;
+    };
+}
+/**
+ * Any decoded channel message. Unknown `type` values are passed through so
+ * forward-compatible servers don't break older SDKs.
+ */
+export type StreamMessage = WelcomeMessage | PriceUpdateMessage | RigCountUpdateMessage | {
+    type: string;
+    [key: string]: unknown;
+};
+/**
+ * Options for {@link StreamingResource.prices}.
+ */
+export interface StreamPricesOptions {
+    /**
+     * Optional client-side filter. When provided, only `price_update` messages
+     * whose normalized map contains at least one of these commodity slugs are
+     * delivered to `onUpdate` / the `price_update` event.
+     *
+     * Accepts the streamed slugs (`"brent"`, `"wti"`, `"uk"`, `"us"`, `"eu"`)
+     * or the upstream codes (`"BRENT_CRUDE_USD"`, `"WTI_USD"`,
+     * `"NATURAL_GAS_GBP"`, `"NATURAL_GAS_USD"`, `"DUTCH_TTF_EUR"`).
+     *
+     * The server broadcasts the full map regardless; filtering is applied
+     * locally so callers can scope updates without extra config.
+     */
+    commodities?: string[];
+    /** Disable automatic reconnection (default: reconnect enabled). */
+    autoReconnect?: boolean;
+    /** Base reconnect delay in ms (default: 1000). */
+    reconnectDelay?: number;
+    /** Maximum reconnect delay in ms for the exponential backoff (default: 30000). */
+    maxReconnectDelay?: number;
+    /**
+     * Maximum number of consecutive reconnect attempts before giving up and
+     * emitting a terminal `error`. `Infinity` to retry forever (default: 10).
+     */
+    maxReconnectAttempts?: number;
+}
+/** Callback invoked for each delivered `price_update` message. */
+export type PriceUpdateHandler = (update: PriceUpdateMessage) => void;
+/**
+ * Handle for an active price stream.
+ *
+ * Extends `EventEmitter`. Emitted events:
+ * - `"connected"` — transport connected and subscription confirmed
+ * - `"welcome"` — initial snapshot ({@link WelcomeMessage})
+ * - `"price_update"` — live price broadcast ({@link PriceUpdateMessage})
+ * - `"rig_count_update"` — drilling broadcast ({@link RigCountUpdateMessage})
+ * - `"message"` — every decoded channel message ({@link StreamMessage})
+ * - `"reconnecting"` — a reconnect attempt is scheduled (`{ attempt, delay }`)
+ * - `"disconnected"` — transport closed (`{ code, reason }`)
+ * - `"error"` — an `Error` (transport error, unauthorized, or retries exhausted)
+ * - `"close"` — the subscription was closed via {@link PriceStreamSubscription.close}
+ */
+export declare class PriceStreamSubscription extends EventEmitter {
+    private readonly wsImpl;
+    private ws;
+    private readonly url;
+    private readonly apiKey;
+    private readonly identifier;
+    private readonly options;
+    private readonly commodityFilter;
+    private closed;
+    private subscribed;
+    private reconnectAttempts;
+    private reconnectTimer;
+    /**
+     * @param url - The `wss://.../cable` endpoint.
+     * @param apiKey - API key sent as the ActionCable `Authorization: Token <key>` header.
+     * @param options - Reconnect + filter options.
+     * @param wsImpl - Injectable WebSocket constructor (used by tests to mock).
+     * @internal Construct via {@link StreamingResource.prices}.
+     */
+    constructor(url: string, apiKey: string, options: StreamPricesOptions, wsImpl?: typeof WebSocket);
+    /**
+     * Open the transport and begin the ActionCable handshake.
+     * @internal Called once by {@link StreamingResource.prices}.
+     */
+    connect(): void;
+    private handleRaw;
+    private dispatch;
+    private matchesFilter;
+    private scheduleReconnect;
+    private send;
+    /** Whether the channel subscription has been confirmed by the server. */
+    get isSubscribed(): boolean;
+    /**
+     * Cleanly tear down the stream: cancels any pending reconnect, unsubscribes
+     * from the channel, and closes the socket. Safe to call multiple times.
+     * Emits `"close"` once.
+     */
+    close(): void;
+}
+/**
+ * Streaming resource — entry point for real-time price subscriptions.
+ *
+ * Accessed via `client.stream`.
+ */
+export declare class StreamingResource {
+    private client;
+    /**
+     * Injectable WebSocket implementation. Defaults to the `ws` package;
+     * tests pass a mock constructor.
+     * @internal
+     */
+    private wsImpl;
+    constructor(client: OilPriceAPI, 
+    /**
+     * Injectable WebSocket implementation. Defaults to the `ws` package;
+     * tests pass a mock constructor.
+     * @internal
+     */
+    wsImpl?: typeof WebSocket);
+    /**
+     * Derive the `wss://.../cable` endpoint from the client's REST base URL.
+     *
+     * `https://api.oilpriceapi.com` -> `wss://api.oilpriceapi.com/cable`
+     * `http://localhost:5000`       -> `ws://localhost:5000/cable`
+     */
+    private cableUrl;
+    /**
+     * Open a real-time price stream over the `EnergyPricesChannel`.
+     *
+     * Returns a {@link PriceStreamSubscription} handle (an `EventEmitter`) you
+     * can attach further listeners to and `.close()` when done. The optional
+     * `onUpdate` callback is a convenience wired to the `price_update` event.
+     *
+     * @param options - Filtering and reconnect options.
+     * @param onUpdate - Optional callback for each `price_update` message.
+     * @returns The subscription handle.
+     *
+     * @throws {OilPriceAPIError} If no API key is configured on the client.
+     *
+     * @example
+     * ```typescript
+     * const client = new OilPriceAPI({ apiKey: process.env.OILPRICEAPI_KEY });
+     *
+     * const sub = client.stream.prices(
+     *   { commodities: ["WTI_USD", "BRENT_CRUDE_USD"] },
+     *   (update) => {
+     *     const wti = update.prices.oil.wti;
+     *     if (wti) console.log(`WTI ${wti.original_price} @ ${update.timestamp}`);
+     *   },
+     * );
+     *
+     * sub.on("connected", () => console.log("streaming live"));
+     * sub.on("error", (err) => console.error("stream error:", err));
+     *
+     * process.on("SIGINT", () => sub.close());
+     * ```
+     */
+    prices(options?: StreamPricesOptions, onUpdate?: PriceUpdateHandler): PriceStreamSubscription;
+}