oilpriceapi 0.7.0 → 0.9.0

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

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * Webhooks Resource
+ *
+ * Manage webhook endpoints for real-time event notifications.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhooksResource = void 0;
+const errors_js_1 = require("../errors.js");
+const index_js_1 = require("../index.js");
+/**
+ * Webhooks Resource
+ *
+ * Manage webhook endpoints for real-time notifications about price changes,
+ * alerts, and other events.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Create a webhook
+ * const webhook = await client.webhooks.create({
+ *   name: 'Price Updates',
+ *   url: 'https://myapp.com/webhooks/prices',
+ *   events: ['price.updated', 'alert.triggered'],
+ *   enabled: true
+ * });
+ *
+ * // Test the webhook
+ * const test = await client.webhooks.test(webhook.id);
+ * console.log(`Test result: ${test.success ? 'passed' : 'failed'}`);
+ *
+ * // List all webhooks
+ * const webhooks = await client.webhooks.list();
+ * webhooks.forEach(wh => {
+ *   console.log(`${wh.name}: ${wh.successful_deliveries} successful`);
+ * });
+ *
+ * // Update webhook
+ * await client.webhooks.update(webhook.id, {
+ *   enabled: false
+ * });
+ *
+ * // Delete webhook
+ * await client.webhooks.delete(webhook.id);
+ * ```
+ */
+class WebhooksResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all webhook endpoints
+     *
+     * @returns Array of webhook endpoints
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const webhooks = await client.webhooks.list();
+     * webhooks.forEach(wh => {
+     *   console.log(`${wh.name} (${wh.enabled ? 'enabled' : 'disabled'})`);
+     *   console.log(`  Events: ${wh.events.join(', ')}`);
+     * });
+     * ```
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/webhooks", {});
+        return Array.isArray(response) ? response : response.webhooks;
+    }
+    /**
+     * Get a specific webhook endpoint
+     *
+     * @param id - Webhook ID
+     * @returns Webhook endpoint details
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.get('webhook-id');
+     * console.log(`${webhook.name}: ${webhook.url}`);
+     * console.log(`Success rate: ${webhook.successful_deliveries}/${webhook.successful_deliveries + webhook.failed_deliveries}`);
+     * ```
+     */
+    async get(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.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;
+    }
+    /**
+     * Create a new webhook endpoint
+     *
+     * @param params - Webhook configuration
+     * @returns Created webhook endpoint
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.create({
+     *   name: 'Production Alerts',
+     *   url: 'https://api.myapp.com/webhooks',
+     *   events: ['alert.triggered', 'price.updated'],
+     *   secret: 'my-webhook-secret',
+     *   enabled: true
+     * });
+     * console.log(`Webhook created: ${webhook.id}`);
+     * ```
+     */
+    async create(params) {
+        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: { ...params },
+        });
+        return "webhook" in response ? response.webhook : response;
+    }
+    /**
+     * Update a webhook endpoint
+     *
+     * @param id - Webhook ID
+     * @param params - Fields to update
+     * @returns Updated webhook endpoint
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * // Disable a webhook
+     * await client.webhooks.update(webhookId, { enabled: false });
+     *
+     * // Change events
+     * await client.webhooks.update(webhookId, {
+     *   events: ['alert.triggered']
+     * });
+     * ```
+     */
+    async update(id, params) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Webhook ID must be a non-empty string");
+        }
+        if (params.url !== undefined && !params.url.startsWith("https://")) {
+            throw new errors_js_1.ValidationError("Webhook URL must use HTTPS protocol");
+        }
+        if (params.events !== undefined &&
+            (!Array.isArray(params.events) || params.events.length === 0)) {
+            throw new errors_js_1.ValidationError("Events must be a non-empty array");
+        }
+        const response = await this.client["request"](`/v1/webhooks/${id}`, {}, {
+            method: "PATCH",
+            body: { ...params },
+        });
+        return "webhook" in response ? response.webhook : response;
+    }
+    /**
+     * Delete a webhook endpoint
+     *
+     * @param id - Webhook ID
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * await client.webhooks.delete(webhookId);
+     * console.log('Webhook deleted');
+     * ```
+     */
+    async delete(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Webhook ID must be a non-empty string");
+        }
+        await this.client["request"](`/v1/webhooks/${id}`, {}, { method: "DELETE" });
+    }
+    /**
+     * Test a webhook endpoint
+     *
+     * Sends a test payload to the webhook URL to verify it's reachable.
+     *
+     * @param id - Webhook ID
+     * @returns Test results
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const test = await client.webhooks.test(webhookId);
+     * console.log(`Test ${test.success ? 'passed' : 'failed'}`);
+     * console.log(`Response time: ${test.response_time_ms}ms`);
+     * if (!test.success) {
+     *   console.log(`Error: ${test.error}`);
+     * }
+     * ```
+     */
+    async test(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Webhook ID must be a non-empty string");
+        }
+        return this.client["request"](`/v1/webhooks/${id}/test`, {}, { method: "POST" });
+    }
+    /**
+     * Get webhook event history
+     *
+     * Returns recent delivery events for a webhook.
+     *
+     * @param id - Webhook ID
+     * @returns Array of webhook events
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const events = await client.webhooks.events(webhookId);
+     * events.forEach(event => {
+     *   console.log(`${event.event_type}: ${event.status} (${event.attempts} attempts)`);
+     * });
+     * ```
+     */
+    async events(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.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 (0, index_js_1.verifyWebhookSignature)(payload, signature, secret);
+    }
+}
+exports.WebhooksResource = WebhooksResource;

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/version.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SDK_NAME = exports.SDK_VERSION = void 0;
+exports.buildUserAgent = buildUserAgent;
+/**
+ * SDK Version - centralized to ensure consistency across all headers
+ *
+ * This version must be updated when publishing a new release.
+ * It's used in:
+ * - User-Agent header: oilpriceapi-node/{version}
+ * - X-Client-Version header
+ * - Package.json (should match)
+ */
+exports.SDK_VERSION = "0.9.0";
+/**
+ * SDK identifier used in User-Agent and X-Api-Client headers
+ */
+exports.SDK_NAME = "oilpriceapi-node";
+/**
+ * Build the full User-Agent string
+ */
+function buildUserAgent() {
+    return `${exports.SDK_NAME}/${exports.SDK_VERSION} node/${process.version}`;
+}