oilpriceapi 0.7.0 → 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
@@ -287,4 +301,40 @@ export declare class WebhooksResource {
      * ```
      */
     events(id: string): Promise<WebhookEvent[]>;
+    /**
+     * Verify a webhook signature.
+     *
+     * Validates that a webhook payload was sent by OilPriceAPI by checking
+     * the HMAC-SHA256 signature. Uses constant-time comparison to prevent
+     * timing attacks.
+     *
+     * @param payload - Raw request body (string or Buffer)
+     * @param signature - Value of the X-OilPriceAPI-Signature header (e.g., "sha256=abc123...")
+     * @param secret - Your webhook signing secret
+     * @returns true if signature is valid
+     *
+     * @example
+     * ```typescript
+     * import express from 'express';
+     * import { OilPriceAPI } from 'oilpriceapi';
+     *
+     * const app = express();
+     * const client = new OilPriceAPI({ apiKey: 'your_key' });
+     *
+     * // Use raw body parser for webhook routes
+     * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+     *   const signature = req.headers['x-oilpriceapi-signature'] as string;
+     *   const isValid = client.webhooks.verifySignature(req.body, signature, 'your_secret');
+     *
+     *   if (!isValid) {
+     *     return res.status(401).send('Invalid signature');
+     *   }
+     *
+     *   const event = JSON.parse(req.body.toString());
+     *   console.log('Verified webhook:', event.type);
+     *   res.sendStatus(200);
+     * });
+     * ```
+     */
+    verifySignature(payload: string | Buffer, signature: string, secret: string): boolean;
 }

package/dist/resources/webhooks.js

@@ -3,6 +3,8 @@
  *
  * Manage webhook endpoints for real-time event notifications.
  */
+import { ValidationError } from "../errors.js";
+import { verifyWebhookSignature } from "../index.js";
 /**
  * Webhooks Resource
  *
@@ -85,7 +87,7 @@ export class WebhooksResource {
      */
     async get(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Webhook ID must be a non-empty string");
+            throw new ValidationError("Webhook ID must be a non-empty string");
         }
         const response = await this.client["request"](`/v1/webhooks/${id}`, {});
         return "webhook" in response ? response.webhook : response;
@@ -112,41 +114,18 @@ export class WebhooksResource {
      * ```
      */
     async create(params) {
-        if (!params.name || typeof params.name !== "string") {
-            throw new Error("Webhook name is required");
-        }
         if (!params.url || !params.url.startsWith("https://")) {
-            throw new Error("Webhook URL must use HTTPS protocol");
+            throw new ValidationError("Webhook URL must use HTTPS protocol");
         }
-        if (!params.events ||
-            !Array.isArray(params.events) ||
-            params.events.length === 0) {
-            throw new Error("At least one event type is required");
+        if (!params.events || !Array.isArray(params.events) || params.events.length === 0) {
+            throw new ValidationError("At least one event type is required");
         }
-        const url = `${this.client["baseUrl"]}/v1/webhooks`;
-        const response = await fetch(url, {
+        // The controller reads a flat (un-nested) body via params.permit(...).
+        const response = await this.client["request"]("/v1/webhooks", {}, {
             method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({
-                webhook: {
-                    name: params.name,
-                    url: params.url,
-                    events: params.events,
-                    enabled: params.enabled ?? true,
-                    secret: params.secret,
-                    metadata: params.metadata,
-                },
-            }),
+            body: { ...params },
         });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to create webhook: ${response.status} ${errorText}`);
-        }
-        const data = (await response.json());
-        return "webhook" in data ? data.webhook : data;
+        return "webhook" in response ? response.webhook : response;
     }
     /**
      * Update a webhook endpoint
@@ -171,32 +150,20 @@ export class WebhooksResource {
      */
     async update(id, params) {
         if (!id || typeof id !== "string") {
-            throw new Error("Webhook ID must be a non-empty string");
+            throw new ValidationError("Webhook ID must be a non-empty string");
         }
         if (params.url !== undefined && !params.url.startsWith("https://")) {
-            throw new Error("Webhook URL must use HTTPS protocol");
+            throw new ValidationError("Webhook URL must use HTTPS protocol");
         }
         if (params.events !== undefined &&
             (!Array.isArray(params.events) || params.events.length === 0)) {
-            throw new Error("Events must be a non-empty array");
+            throw new ValidationError("Events must be a non-empty array");
         }
-        const url = `${this.client["baseUrl"]}/v1/webhooks/${id}`;
-        const response = await fetch(url, {
+        const response = await this.client["request"](`/v1/webhooks/${id}`, {}, {
             method: "PATCH",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({
-                webhook: params,
-            }),
+            body: { ...params },
         });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to update webhook: ${response.status} ${errorText}`);
-        }
-        const data = (await response.json());
-        return "webhook" in data ? data.webhook : data;
+        return "webhook" in response ? response.webhook : response;
     }
     /**
      * Delete a webhook endpoint
@@ -214,20 +181,9 @@ export class WebhooksResource {
      */
     async delete(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Webhook ID must be a non-empty string");
-        }
-        const url = `${this.client["baseUrl"]}/v1/webhooks/${id}`;
-        const response = await fetch(url, {
-            method: "DELETE",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-        });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to delete webhook: ${response.status} ${errorText}`);
+            throw new ValidationError("Webhook ID must be a non-empty string");
         }
+        await this.client["request"](`/v1/webhooks/${id}`, {}, { method: "DELETE" });
     }
     /**
      * Test a webhook endpoint
@@ -252,21 +208,9 @@ export class WebhooksResource {
      */
     async test(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Webhook ID must be a non-empty string");
-        }
-        const url = `${this.client["baseUrl"]}/v1/webhooks/${id}/test`;
-        const response = await fetch(url, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-        });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to test webhook: ${response.status} ${errorText}`);
+            throw new ValidationError("Webhook ID must be a non-empty string");
         }
-        return response.json();
+        return this.client["request"](`/v1/webhooks/${id}/test`, {}, { method: "POST" });
     }
     /**
      * Get webhook event history
@@ -289,9 +233,47 @@ export class WebhooksResource {
      */
     async events(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Webhook ID must be a non-empty string");
+            throw new ValidationError("Webhook ID must be a non-empty string");
         }
         const response = await this.client["request"](`/v1/webhooks/${id}/events`, {});
         return Array.isArray(response) ? response : response.events;
     }
+    /**
+     * Verify a webhook signature.
+     *
+     * Validates that a webhook payload was sent by OilPriceAPI by checking
+     * the HMAC-SHA256 signature. Uses constant-time comparison to prevent
+     * timing attacks.
+     *
+     * @param payload - Raw request body (string or Buffer)
+     * @param signature - Value of the X-OilPriceAPI-Signature header (e.g., "sha256=abc123...")
+     * @param secret - Your webhook signing secret
+     * @returns true if signature is valid
+     *
+     * @example
+     * ```typescript
+     * import express from 'express';
+     * import { OilPriceAPI } from 'oilpriceapi';
+     *
+     * const app = express();
+     * const client = new OilPriceAPI({ apiKey: 'your_key' });
+     *
+     * // Use raw body parser for webhook routes
+     * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+     *   const signature = req.headers['x-oilpriceapi-signature'] as string;
+     *   const isValid = client.webhooks.verifySignature(req.body, signature, 'your_secret');
+     *
+     *   if (!isValid) {
+     *     return res.status(401).send('Invalid signature');
+     *   }
+     *
+     *   const event = JSON.parse(req.body.toString());
+     *   console.log('Verified webhook:', event.type);
+     *   res.sendStatus(200);
+     * });
+     * ```
+     */
+    verifySignature(payload, signature, secret) {
+        return verifyWebhookSignature(payload, signature, secret);
+    }
 }