oilpriceapi 0.8.2 → 0.9.1

package/dist/cjs/resources/streaming.js

@@ -0,0 +1,350 @@
+"use strict";
+/**
+ * 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();
+ * ```
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamingResource = exports.PriceStreamSubscription = exports.ENERGY_PRICES_CHANNEL = void 0;
+const node_events_1 = require("node:events");
+const ws_1 = __importDefault(require("ws"));
+/**
+ * The ActionCable channel exposed by the OilPriceAPI server.
+ *
+ * Confirmed from `app/channels/energy_prices_channel.rb`
+ * (`class EnergyPricesChannel`).
+ */
+exports.ENERGY_PRICES_CHANNEL = "EnergyPricesChannel";
+/** Maps streamed slug <-> upstream code so `commodities` filtering accepts either. */
+const COMMODITY_CODE_TO_SLUG = {
+    BRENT_CRUDE_USD: "brent",
+    WTI_USD: "wti",
+    NATURAL_GAS_GBP: "uk",
+    NATURAL_GAS_USD: "us",
+    DUTCH_TTF_EUR: "eu",
+};
+/**
+ * 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}
+ */
+class PriceStreamSubscription extends node_events_1.EventEmitter {
+    /**
+     * @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, apiKey, options, wsImpl = ws_1.default) {
+        super();
+        this.wsImpl = wsImpl;
+        this.ws = null;
+        this.closed = false;
+        this.subscribed = false;
+        this.reconnectAttempts = 0;
+        this.reconnectTimer = null;
+        this.url = url;
+        this.apiKey = apiKey;
+        this.options = {
+            autoReconnect: options.autoReconnect ?? true,
+            reconnectDelay: options.reconnectDelay ?? 1000,
+            maxReconnectDelay: options.maxReconnectDelay ?? 30000,
+            maxReconnectAttempts: options.maxReconnectAttempts ?? 10,
+            commodities: options.commodities,
+        };
+        // The ActionCable subscription identifier. The channel takes no params;
+        // we additionally pass `api_key` in the identifier for parity with the
+        // documented native-WebSocket clients, while the server's
+        // ApplicationCable::Connection authenticates from the Authorization header.
+        this.identifier = JSON.stringify({
+            channel: exports.ENERGY_PRICES_CHANNEL,
+            api_key: apiKey,
+        });
+        if (options.commodities && options.commodities.length > 0) {
+            this.commodityFilter = new Set(options.commodities.map((c) => COMMODITY_CODE_TO_SLUG[c] ?? c.toLowerCase()));
+        }
+        else {
+            this.commodityFilter = null;
+        }
+    }
+    /**
+     * Open the transport and begin the ActionCable handshake.
+     * @internal Called once by {@link StreamingResource.prices}.
+     */
+    connect() {
+        if (this.closed)
+            return;
+        const ws = new this.wsImpl(this.url, {
+            headers: {
+                Authorization: `Token ${this.apiKey}`,
+            },
+        });
+        this.ws = ws;
+        ws.on("open", () => {
+            // ActionCable sends a transport `welcome` frame first; we subscribe on
+            // open (the server tolerates an early subscribe and replies with
+            // confirm_subscription once the connection is established).
+            this.send({ command: "subscribe", identifier: this.identifier });
+        });
+        ws.on("message", (raw) => this.handleRaw(raw));
+        ws.on("error", (err) => {
+            this.emit("error", err);
+        });
+        ws.on("close", (code, reason) => {
+            this.ws = null;
+            this.subscribed = false;
+            this.emit("disconnected", { code, reason: reason?.toString() ?? "" });
+            if (!this.closed) {
+                this.scheduleReconnect();
+            }
+        });
+    }
+    handleRaw(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw.toString());
+        }
+        catch {
+            // Ignore malformed frames rather than crash the stream.
+            return;
+        }
+        // ActionCable transport-level frames carry a top-level `type`.
+        const transportType = frame["type"];
+        if (transportType === "ping") {
+            // Heartbeat — nothing to do; presence of frames keeps `ws` alive.
+            return;
+        }
+        if (transportType === "welcome") {
+            // Transport handshake complete. (subscribe already sent on open.)
+            return;
+        }
+        if (transportType === "confirm_subscription") {
+            this.subscribed = true;
+            this.reconnectAttempts = 0;
+            this.emit("connected");
+            return;
+        }
+        if (transportType === "reject_subscription") {
+            this.emit("error", new Error("WebSocket subscription rejected. Streaming requires a Reservoir Mastery " +
+                "(Professional+) plan and a valid API key."));
+            return;
+        }
+        if (transportType === "disconnect") {
+            // Server-initiated disconnect (e.g. auth failure). Let `close` drive reconnect.
+            return;
+        }
+        // Channel message: payload lives under `message`.
+        const payload = frame["message"];
+        if (payload && typeof payload === "object") {
+            this.dispatch(payload);
+        }
+    }
+    dispatch(message) {
+        this.emit("message", message);
+        switch (message.type) {
+            case "welcome":
+                this.emit("welcome", message);
+                break;
+            case "price_update": {
+                const update = message;
+                if (this.matchesFilter(update)) {
+                    this.emit("price_update", update);
+                }
+                break;
+            }
+            case "rig_count_update":
+                this.emit("rig_count_update", message);
+                break;
+            default:
+                // Unknown message types are still emitted via `message` above.
+                break;
+        }
+    }
+    matchesFilter(update) {
+        if (!this.commodityFilter)
+            return true;
+        const { oil, natural_gas } = update.prices ?? {};
+        const present = {
+            brent: oil?.brent,
+            wti: oil?.wti,
+            uk: natural_gas?.uk,
+            us: natural_gas?.us,
+            eu: natural_gas?.eu,
+        };
+        for (const slug of this.commodityFilter) {
+            if (present[slug])
+                return true;
+        }
+        return false;
+    }
+    scheduleReconnect() {
+        if (this.closed || !this.options.autoReconnect)
+            return;
+        if (this.reconnectAttempts >= this.options.maxReconnectAttempts) {
+            this.emit("error", new Error(`WebSocket reconnect failed after ${this.reconnectAttempts} attempt(s); giving up.`));
+            return;
+        }
+        const attempt = this.reconnectAttempts++;
+        const delay = Math.min(this.options.reconnectDelay * Math.pow(2, attempt), this.options.maxReconnectDelay);
+        this.emit("reconnecting", { attempt: attempt + 1, delay });
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    send(payload) {
+        if (this.ws && this.ws.readyState === this.wsImpl.OPEN) {
+            this.ws.send(JSON.stringify(payload));
+        }
+    }
+    /** Whether the channel subscription has been confirmed by the server. */
+    get isSubscribed() {
+        return this.subscribed;
+    }
+    /**
+     * 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() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            const ws = this.ws;
+            try {
+                if (ws.readyState === this.wsImpl.OPEN) {
+                    ws.send(JSON.stringify({ command: "unsubscribe", identifier: this.identifier }));
+                }
+            }
+            catch {
+                // ignore — we're closing anyway
+            }
+            try {
+                ws.close();
+            }
+            catch {
+                // ignore
+            }
+            this.ws = null;
+        }
+        this.subscribed = false;
+        this.emit("close");
+        this.removeAllListeners();
+    }
+}
+exports.PriceStreamSubscription = PriceStreamSubscription;
+/**
+ * Streaming resource — entry point for real-time price subscriptions.
+ *
+ * Accessed via `client.stream`.
+ */
+class StreamingResource {
+    constructor(client, 
+    /**
+     * Injectable WebSocket implementation. Defaults to the `ws` package;
+     * tests pass a mock constructor.
+     * @internal
+     */
+    wsImpl = ws_1.default) {
+        this.client = client;
+        this.wsImpl = wsImpl;
+    }
+    /**
+     * 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`
+     */
+    cableUrl() {
+        const base = this.client["baseUrl"];
+        const wsBase = base
+            .replace(/^http:/, "ws:")
+            .replace(/^https:/, "wss:")
+            .replace(/\/$/, "");
+        return `${wsBase}/cable`;
+    }
+    /**
+     * 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 = {}, onUpdate) {
+        const apiKey = this.client["apiKey"];
+        const sub = new PriceStreamSubscription(this.cableUrl(), apiKey, options, this.wsImpl);
+        if (onUpdate) {
+            sub.on("price_update", onUpdate);
+        }
+        sub.connect();
+        return sub;
+    }
+}
+exports.StreamingResource = StreamingResource;

package/dist/cjs/resources/webhooks.js

@@ -117,27 +117,16 @@ class WebhooksResource {
      * ```
      */
     async create(params) {
-        if (!params.name || typeof params.name !== "string") {
-            throw new errors_js_1.ValidationError("Webhook name is required");
-        }
         if (!params.url || !params.url.startsWith("https://")) {
             throw new errors_js_1.ValidationError("Webhook URL must use HTTPS protocol");
         }
         if (!params.events || !Array.isArray(params.events) || params.events.length === 0) {
             throw new errors_js_1.ValidationError("At least one event type is required");
         }
+        // The controller reads a flat (un-nested) body via params.permit(...).
         const response = await this.client["request"]("/v1/webhooks", {}, {
             method: "POST",
-            body: {
-                webhook: {
-                    name: params.name,
-                    url: params.url,
-                    events: params.events,
-                    enabled: params.enabled ?? true,
-                    secret: params.secret,
-                    metadata: params.metadata,
-                },
-            },
+            body: { ...params },
         });
         return "webhook" in response ? response.webhook : response;
     }
@@ -175,7 +164,7 @@ class WebhooksResource {
         }
         const response = await this.client["request"](`/v1/webhooks/${id}`, {}, {
             method: "PATCH",
-            body: { webhook: params },
+            body: { ...params },
         });
         return "webhook" in response ? response.webhook : response;
     }

package/dist/cjs/version.js

@@ -11,7 +11,7 @@ exports.buildUserAgent = buildUserAgent;
  * - X-Client-Version header
  * - Package.json (should match)
  */
-exports.SDK_VERSION = "0.8.2";
+exports.SDK_VERSION = "0.9.1";
 /**
  * SDK identifier used in User-Agent and X-Api-Client headers
  */

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { OilPriceAPIConfig, Price, LatestPricesOptions, HistoricalPricesOptions, Commodity, CommoditiesResponse, CategoriesResponse, DataConnectorPrice, DataConnectorOptions } from "./types.js";
+import type { OilPriceAPIConfig, Price, LatestPricesOptions, HistoricalPricesOptions, Commodity, CommoditiesResponse, CategoriesResponse, DataConnectorPrice, DataConnectorOptions, DemoPricesResponse, DemoCommoditiesResponse } from "./types.js";
 import { DieselResource } from "./resources/diesel.js";
 import { AlertsResource } from "./resources/alerts.js";
 import { CommoditiesResource } from "./resources/commodities.js";
@@ -13,6 +13,26 @@ import { DrillingIntelligenceResource } from "./resources/drilling.js";
 import { EnergyIntelligenceResource } from "./resources/ei/index.js";
 import { WebhooksResource } from "./resources/webhooks.js";
 import { DataSourcesResource } from "./resources/data-sources.js";
+import { SpreadsResource } from "./resources/spreads.js";
+import { IndicatorsResource } from "./resources/indicators.js";
+import { RawResource } from "./resources/raw.js";
+import { StreamingResource } from "./resources/streaming.js";
+/**
+ * Raw HTTP response wrapper.
+ *
+ * Returned by {@link OilPriceAPI.raw} accessors to expose the underlying
+ * HTTP status code and response headers alongside the parsed data.
+ *
+ * @typeParam T - The parsed response body type.
+ */
+export interface APIResponse<T> {
+    /** Parsed response data (same shape the non-raw method would return). */
+    data: T;
+    /** HTTP status code (e.g., 200, 201). */
+    status: number;
+    /** Response headers. */
+    headers: Headers;
+}
 /**
  * Official Node.js client for Oil Price API
  *
@@ -105,6 +125,28 @@ export declare class OilPriceAPI {
      * Data sources resource (BYOS - Bring Your Own Source)
      */
     readonly dataSources: DataSourcesResource;
+    /**
+     * Spreads resource (crack, basis, curve structure, margin, physical premium)
+     */
+    readonly spreads: SpreadsResource;
+    /**
+     * Indicators resource (fuel switching, price context, storage analytics,
+     * annotations, CFTC positioning, congressional trades)
+     */
+    readonly indicators: IndicatorsResource;
+    /**
+     * Raw-response accessor.
+     *
+     * Mirrors the top-level price/commodity methods but returns the underlying
+     * HTTP status and headers alongside the parsed data via {@link APIResponse}.
+     */
+    readonly raw: RawResource;
+    /**
+     * Real-time price streaming resource (WebSocket / ActionCable).
+     *
+     * Streaming requires a Reservoir Mastery (Professional+) plan.
+     */
+    readonly stream: StreamingResource;
     constructor(config?: OilPriceAPIConfig);
     /**
      * Log debug messages if debug mode is enabled
@@ -122,12 +164,29 @@ export declare class OilPriceAPI {
      * Determine if error is retryable
      */
     private isRetryable;
+    /**
+     * Shape a parsed JSON response body into the value returned to callers.
+     *
+     * Centralizes the response-structure handling so that both {@link request}
+     * and {@link requestRaw} return identical data. Handles the latest/historical
+     * envelope shapes as well as the generic `{ data }` fallback used by resource
+     * mutations, alerts, webhooks, etc.
+     */
+    private shapeResponseData;
     /**
      * Internal method to make HTTP requests with retry and timeout.
      * Supports all HTTP methods (GET, POST, PATCH, DELETE) with consistent
      * retry logic, timeout handling, and typed error responses.
      */
     private request;
+    /**
+     * Internal method identical to {@link request} but returns the underlying
+     * HTTP status and headers alongside the parsed data.
+     *
+     * Used by the public {@link raw} accessor to expose response metadata
+     * (issue #7) without changing the return shape of existing methods.
+     */
+    private requestRaw;
     /**
      * Get the latest prices for all commodities or a specific commodity
      *
@@ -252,4 +311,41 @@ export declare class OilPriceAPI {
      * ```
      */
     getCommodity(code: string): Promise<Commodity>;
+    /**
+     * Fetch live sample prices from the public, no-auth demo endpoint.
+     *
+     * Hits `GET /v1/demo/prices` (no API key required) and returns the parsed
+     * `{ prices, meta }` envelope. Useful for trying the client without
+     * credentials. Subject to the demo rate limit (~20 requests/hour).
+     *
+     * @example
+     * ```typescript
+     * const demo = await client.getDemoPrices();
+     * const brent = demo.prices.find(p => p.code === 'BRENT_CRUDE_USD');
+     * console.log(brent?.price);
+     * ```
+     */
+    getDemoPrices(): Promise<DemoPricesResponse>;
+    /**
+     * Fetch the catalogue of commodities from the public, no-auth demo endpoint.
+     *
+     * Hits `GET /v1/demo/commodities` (no API key required) and returns the parsed
+     * `{ commodities, meta }` envelope, where `meta.free_commodities` lists the
+     * codes available on the free demo tier.
+     *
+     * @example
+     * ```typescript
+     * const demo = await client.getDemoCommodities();
+     * console.log(demo.meta.total, demo.meta.free_commodities);
+     * ```
+     */
+    getDemoCommodities(): Promise<DemoCommoditiesResponse>;
+    /**
+     * Minimal fetch for the no-auth demo endpoints.
+     *
+     * Unlike {@link request}, this does NOT run the latest/historical response
+     * shaping (which would strip the `meta` block) and does NOT require an API
+     * key — it returns the raw `data` envelope from `{ status, data }`.
+     */
+    private requestDemo;
 }