oilpriceapi 0.8.2 → 0.9.0

package/dist/resources/streaming.js

@@ -0,0 +1,342 @@
+/**
+ * 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";
+/**
+ * The ActionCable channel exposed by the OilPriceAPI server.
+ *
+ * Confirmed from `app/channels/energy_prices_channel.rb`
+ * (`class EnergyPricesChannel`).
+ */
+export const 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}
+ */
+export class PriceStreamSubscription extends 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 = WebSocket) {
+        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: 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();
+    }
+}
+/**
+ * Streaming resource — entry point for real-time price subscriptions.
+ *
+ * Accessed via `client.stream`.
+ */
+export class StreamingResource {
+    constructor(client, 
+    /**
+     * Injectable WebSocket implementation. Defaults to the `ws` package;
+     * tests pass a mock constructor.
+     * @internal
+     */
+    wsImpl = WebSocket) {
+        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;
+    }
+}

package/dist/resources/webhooks.d.ts

@@ -10,18 +10,16 @@ import type { OilPriceAPI } from "../client.js";
 export interface WebhookEndpoint {
     /** Unique webhook identifier */
     id: string;
-    /** User-friendly webhook name */
-    name: string;
+    /** User-friendly description of the webhook */
+    description?: string;
     /** Webhook URL (must be HTTPS) */
     url: string;
     /** Event types to subscribe to */
     events: string[];
-    /** Whether the webhook is active */
-    enabled: boolean;
-    /** Optional secret for signature verification */
+    /** Lifecycle status (e.g. 'active', 'disabled') */
+    status?: string;
+    /** Optional secret for signature verification (generated server-side) */
     secret?: string;
-    /** Optional metadata */
-    metadata?: Record<string, unknown>;
     /** Number of successful deliveries */
     successful_deliveries: number;
     /** Number of failed deliveries */
@@ -37,37 +35,53 @@ export interface WebhookEndpoint {
 }
 /**
  * Parameters for creating a webhook
+ *
+ * NOTE: The API permits a flat (un-nested) body with the fields below. Earlier
+ * SDK versions nested these under a `webhook` key and used `name`/`enabled`,
+ * which the controller dropped — the controller reads `description` and `status`.
  */
 export interface CreateWebhookParams {
-    /** User-friendly webhook name */
-    name: string;
     /** Webhook URL (must be HTTPS) */
     url: string;
     /** Event types to subscribe to */
     events: string[];
-    /** Whether to enable immediately (default: true) */
-    enabled?: boolean;
-    /** Optional secret for signature verification */
-    secret?: string;
-    /** Optional metadata */
-    metadata?: Record<string, unknown>;
+    /** User-friendly description */
+    description?: string;
+    /** Lifecycle status (e.g. 'active', 'disabled') */
+    status?: string;
+    /** Commodity codes to filter events to */
+    commodity_filters?: string[];
+    /** US state codes to filter events to */
+    state_filters?: string[];
+    /** Per-second delivery rate limit */
+    rate_limit_per_second?: number;
+    /** Delivery timeout in seconds */
+    timeout_seconds?: number;
+    /** Max delivery retry attempts */
+    max_retries?: number;
 }
 /**
  * Parameters for updating a webhook
  */
 export interface UpdateWebhookParams {
-    /** User-friendly webhook name */
-    name?: string;
     /** Webhook URL */
     url?: string;
     /** Event types to subscribe to */
     events?: string[];
-    /** Whether the webhook is active */
-    enabled?: boolean;
-    /** Secret for signature verification */
-    secret?: string;
-    /** Metadata */
-    metadata?: Record<string, unknown>;
+    /** User-friendly description */
+    description?: string;
+    /** Lifecycle status (e.g. 'active', 'disabled') */
+    status?: string;
+    /** Commodity codes to filter events to */
+    commodity_filters?: string[];
+    /** US state codes to filter events to */
+    state_filters?: string[];
+    /** Per-second delivery rate limit */
+    rate_limit_per_second?: number;
+    /** Delivery timeout in seconds */
+    timeout_seconds?: number;
+    /** Max delivery retry attempts */
+    max_retries?: number;
 }
 /**
  * Webhook test response

package/dist/resources/webhooks.js

@@ -114,27 +114,16 @@ export class WebhooksResource {
      * ```
      */
     async create(params) {
-        if (!params.name || typeof params.name !== "string") {
-            throw new ValidationError("Webhook name is required");
-        }
         if (!params.url || !params.url.startsWith("https://")) {
             throw new ValidationError("Webhook URL must use HTTPS protocol");
         }
         if (!params.events || !Array.isArray(params.events) || params.events.length === 0) {
             throw new 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;
     }
@@ -172,7 +161,7 @@ export 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/types.d.ts

@@ -240,6 +240,47 @@ export interface Commodity {
 export interface CommoditiesResponse {
     commodities: Commodity[];
 }
+/**
+ * A single price entry from the no-auth demo prices endpoint.
+ */
+export interface DemoPrice {
+    code: string;
+    name: string;
+    price: number;
+    currency: string;
+    updated_at: string;
+    change_24h?: number;
+    source?: string;
+}
+/**
+ * Parsed response from the no-auth `GET /v1/demo/prices` endpoint.
+ */
+export interface DemoPricesResponse {
+    prices: DemoPrice[];
+    meta: {
+        demo_mode?: boolean;
+        rate_limit?: string;
+        available_commodities?: number;
+        [key: string]: unknown;
+    };
+    examples?: unknown;
+}
+/**
+ * Parsed response from the no-auth `GET /v1/demo/commodities` endpoint.
+ */
+export interface DemoCommoditiesResponse {
+    /** Commodities grouped by category key. */
+    commodities: Record<string, Commodity[]>;
+    meta: {
+        /** Total number of demo-listed commodities. */
+        total: number;
+        /** Category keys present in the listing. */
+        categories: string[];
+        /** Commodity codes available on the free demo tier. */
+        free_commodities: string[];
+        [key: string]: unknown;
+    };
+}
 /**
  * Category with its commodities
  */

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oilpriceapi",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Official Node.js SDK for Oil Price API - Real-time and historical oil & commodity prices",
   "type": "module",
   "main": "./dist/cjs/index.js",
@@ -27,6 +27,7 @@
     "lint": "eslint src/",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:live": "vitest run --config vitest.live.config.ts",
     "docs": "typedoc",
     "prepublishOnly": "npm run build"
   },
@@ -62,10 +63,15 @@
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
+    "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^4.0.16",
     "eslint": "^9.39.4",
+    "typedoc": "^0.27.9",
     "typescript": "^5.3.0",
     "typescript-eslint": "^8.57.2",
     "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "ws": "^8.21.0"
   }
 }