oilpriceapi 0.7.0 → 0.9.0

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

@@ -4,6 +4,7 @@
  * Access crude oil storage data including total US inventory, Cushing hub levels,
  * Strategic Petroleum Reserve (SPR), and regional breakdowns.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Storage Resource
  *
@@ -148,14 +149,14 @@ export class StorageResource {
      */
     async history(code, options) {
         if (!code || typeof code !== "string") {
-            throw new Error("Storage location code must be a non-empty string");
+            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;
+}