oilpriceapi 0.9.1 → 0.10.0

package/README.md

@@ -26,6 +26,7 @@ The official Node.js/TypeScript SDK for [OilPriceAPI](https://www.oilpriceapi.co
 - 🔔 **NEW v0.5.0** - Price alerts with webhook notifications
 - 📊 **NEW v0.7.0** - Futures, storage, rig counts, analytics, drilling intelligence, webhooks, and energy intelligence
 - 🧰 **NEW** - Typed ICE Brent / Gasoil / WTI & gas/carbon futures helpers, `spreads`, `indicators`, and raw HTTP responses (`client.raw.*` with status + headers)
+- 🤖 **NEW v0.10.0** - `getMarketBrief()` (multi-commodity structured + narrative summary) and agent `subscriptions` (persistent watches + event polling)
 
 ## Installation
 
@@ -645,8 +646,8 @@ logs.forEach((log) => {
 
 Stream live price updates over a persistent WebSocket connection instead of
 polling. Streaming uses the server's ActionCable `/cable` endpoint and the
-`EnergyPricesChannel`, and is available on the **Reservoir Mastery
-(Professional+)** plan.
+`EnergyPricesChannel`, and is available on the **Professional plan
+($99/mo) or higher**.
 
 The `client.stream.prices()` method returns a subscription handle (an
 `EventEmitter`). It performs the ActionCable handshake, answers server pings,
@@ -704,6 +705,81 @@ process.on("SIGINT", () => {
 
 See [`examples/streaming.ts`](./examples/streaming.ts) for a complete runnable example.
 
+### Market Brief (New in v0.10.0)
+
+A single call returns a structured, multi-commodity market summary — latest
+price, 24h change, freshness, and a 1-month forecast band per commodity — with
+an optional natural-language narrative. Counts as one request against your quota.
+
+```typescript
+import { OilPriceAPI } from "oilpriceapi";
+
+const client = new OilPriceAPI({ apiKey: "your_api_key" });
+
+const brief = await client.getMarketBrief(["BRENT_CRUDE_USD", "WTI_USD"]);
+
+for (const c of brief.commodities) {
+  console.log(`${c.name}: $${c.price} (${c.change_24h_pct}% 24h)`);
+  if (c.forecast_1m) {
+    console.log(
+      `  1m forecast: ${c.forecast_1m.point} [${c.forecast_1m.low}–${c.forecast_1m.high}]`,
+    );
+  }
+}
+
+// Include a natural-language narrative
+const withNarrative = await client.getMarketBrief(["BRENT_CRUDE_USD"], {
+  narrative: true,
+});
+console.log(withNarrative.narrative);
+```
+
+### Agent Subscriptions / Watches (New in v0.10.0)
+
+Persistent server-side "watches" evaluate a set of commodity codes on a recurring
+interval and emit events you can poll for — ideal for autonomous agents that want
+change notifications without holding an open connection. The friendly `interval`
+("5m" / "15m" / "1h" / "daily", or a number of seconds) is mapped to the API's
+`interval_seconds`. Polling for events does **not** consume your request quota.
+
+```typescript
+import { OilPriceAPI } from "oilpriceapi";
+
+const client = new OilPriceAPI({ apiKey: "your_api_key" });
+
+// Create a watch (source defaults to "sdk-node"; pass `tool` for attribution)
+const watch = await client.subscriptions.create({
+  name: "Crude desk",
+  codes: ["BRENT_CRUDE_USD", "WTI_USD"],
+  interval: "5m",
+  tool: "my-trading-bot",
+});
+
+// List all watches
+const watches = await client.subscriptions.list();
+console.log(`You have ${watches.length} watch(es)`);
+
+// Poll for new events using a cursor (does not burn quota)
+let cursor = 0;
+while (true) {
+  const {
+    events,
+    cursor: next,
+    has_more,
+  } = await client.subscriptions.events({
+    since: cursor,
+  });
+  for (const event of events) {
+    console.log(`event #${event.seq} on ${event.code} (${event.type})`);
+  }
+  cursor = next;
+  if (!has_more) break;
+}
+
+// Remove a watch when you're done
+await client.subscriptions.delete(watch.id);
+```
+
 ### Advanced Configuration
 
 ```typescript

package/dist/cjs/client.js

@@ -21,6 +21,7 @@ const spreads_js_1 = require("./resources/spreads.js");
 const indicators_js_1 = require("./resources/indicators.js");
 const raw_js_1 = require("./resources/raw.js");
 const streaming_js_1 = require("./resources/streaming.js");
+const subscriptions_js_1 = require("./resources/subscriptions.js");
 /**
  * Official Node.js client for Oil Price API
  *
@@ -80,6 +81,7 @@ class OilPriceAPI {
         this.indicators = new indicators_js_1.IndicatorsResource(this);
         this.raw = new raw_js_1.RawResource(this);
         this.stream = new streaming_js_1.StreamingResource(this);
+        this.subscriptions = new subscriptions_js_1.SubscriptionsResource(this);
     }
     /**
      * Log debug messages if debug mode is enabled
@@ -215,6 +217,14 @@ class OilPriceAPI {
                     if (this.appName) {
                         headers["X-App-Name"] = this.appName;
                     }
+                    // Per-request headers (e.g. MCP attribution X-OPA-Source / X-OPA-Tool).
+                    if (options?.headers) {
+                        Object.entries(options.headers).forEach(([key, value]) => {
+                            if (value !== undefined && value !== null) {
+                                headers[key] = value;
+                            }
+                        });
+                    }
                     const fetchOptions = {
                         method: options?.method || "GET",
                         headers,
@@ -524,6 +534,45 @@ class OilPriceAPI {
     async getCommodity(code) {
         return this.request(`/v1/commodities/${code}`, {});
     }
+    /**
+     * Get a multi-commodity market brief (OilPriceAPI #3245 Phase 1a).
+     *
+     * Returns a structured summary (latest price, 24h change, freshness, and a
+     * 1-month forecast band) for each requested commodity, optionally with a
+     * natural-language narrative. Counts as a single request against your quota,
+     * like `/v1/prices/batch`. The per-tier cap on `codes` is enforced server-side.
+     *
+     * @param codes - Commodity codes (e.g. ["BRENT_CRUDE_USD", "WTI_USD"]). Shorthand
+     *   codes like "WTI"/"BRENT" are accepted and resolved server-side.
+     * @param options - `{ narrative }` to request the natural-language summary.
+     * @returns The structured (and optional narrative) market brief.
+     *
+     * @throws {ValidationError} If `codes` is empty.
+     *
+     * @example
+     * ```typescript
+     * const brief = await client.getMarketBrief(['BRENT_CRUDE_USD', 'WTI_USD']);
+     * for (const c of brief.commodities) {
+     *   console.log(`${c.name}: $${c.price} (${c.change_24h_pct}%)`);
+     * }
+     *
+     * // With narrative
+     * const withText = await client.getMarketBrief(['BRENT_CRUDE_USD'], { narrative: true });
+     * console.log(withText.narrative);
+     * ```
+     */
+    async getMarketBrief(codes, options) {
+        if (!Array.isArray(codes) || codes.length === 0) {
+            throw new errors_js_1.ValidationError("codes is required and must be a non-empty array of commodity codes");
+        }
+        const params = {
+            codes: codes.join(","),
+        };
+        if (options?.narrative) {
+            params.narrative = "true";
+        }
+        return this.request("/v1/market-brief", params);
+    }
     /**
      * Fetch live sample prices from the public, no-auth demo endpoint.
      *

package/dist/cjs/index.js

@@ -7,7 +7,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ENERGY_PRICES_CHANNEL = exports.PriceStreamSubscription = exports.StreamingResource = exports.DataSourcesResource = exports.WebhooksResource = exports.EIFracFocusResource = exports.EIWellPermitsResource = exports.EIForecastsResource = exports.EIDrillingProductivityResource = exports.EIOPECProductionResource = exports.EIOilInventoriesResource = exports.EIRigCountsResource = exports.EnergyIntelligenceResource = exports.DrillingIntelligenceResource = exports.DataQualityResource = exports.ForecastsResource = exports.AnalyticsResource = exports.BunkerFuelsResource = exports.RigCountsResource = exports.StorageResource = exports.FuturesResource = exports.CommoditiesResource = exports.AlertsResource = exports.DieselResource = exports.TimeoutError = exports.ValidationError = exports.ServerError = exports.NotFoundError = exports.RateLimitError = exports.AuthenticationError = exports.OilPriceAPIError = exports.RawResource = exports.IndicatorsResource = exports.SpreadsResource = exports.FuturesContractFamily = exports.FUTURES_FAMILY_SLUGS = exports.FUTURES_CONTRACTS = exports.SDK_NAME = exports.SDK_VERSION = exports.OilPriceAPI = void 0;
+exports.ENERGY_PRICES_CHANNEL = exports.PriceStreamSubscription = exports.StreamingResource = exports.DataSourcesResource = exports.WebhooksResource = exports.EIFracFocusResource = exports.EIWellPermitsResource = exports.EIForecastsResource = exports.EIDrillingProductivityResource = exports.EIOPECProductionResource = exports.EIOilInventoriesResource = exports.EIRigCountsResource = exports.EnergyIntelligenceResource = exports.DrillingIntelligenceResource = exports.DataQualityResource = exports.ForecastsResource = exports.AnalyticsResource = exports.BunkerFuelsResource = exports.RigCountsResource = exports.StorageResource = exports.FuturesResource = exports.CommoditiesResource = exports.AlertsResource = exports.DieselResource = exports.TimeoutError = exports.ValidationError = exports.ServerError = exports.NotFoundError = exports.RateLimitError = exports.AuthenticationError = exports.OilPriceAPIError = exports.intervalToSeconds = exports.SubscriptionsResource = exports.RawResource = exports.IndicatorsResource = exports.SpreadsResource = exports.FuturesContractFamily = exports.FUTURES_FAMILY_SLUGS = exports.FUTURES_CONTRACTS = exports.SDK_NAME = exports.SDK_VERSION = exports.OilPriceAPI = void 0;
 exports.verifyWebhookSignature = verifyWebhookSignature;
 const node_crypto_1 = require("node:crypto");
 var client_js_1 = require("./client.js");
@@ -25,6 +25,9 @@ var indicators_js_1 = require("./resources/indicators.js");
 Object.defineProperty(exports, "IndicatorsResource", { enumerable: true, get: function () { return indicators_js_1.IndicatorsResource; } });
 var raw_js_1 = require("./resources/raw.js");
 Object.defineProperty(exports, "RawResource", { enumerable: true, get: function () { return raw_js_1.RawResource; } });
+var subscriptions_js_1 = require("./resources/subscriptions.js");
+Object.defineProperty(exports, "SubscriptionsResource", { enumerable: true, get: function () { return subscriptions_js_1.SubscriptionsResource; } });
+Object.defineProperty(exports, "intervalToSeconds", { enumerable: true, get: function () { return subscriptions_js_1.intervalToSeconds; } });
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "OilPriceAPIError", { enumerable: true, get: function () { return errors_js_1.OilPriceAPIError; } });
 Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });

package/dist/cjs/resources/market-brief.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Market Brief types (OilPriceAPI #3245 Phase 1a)
+ *
+ * A multi-commodity structured (+ optional narrative) market summary composed
+ * from existing price + forecast data. Served by `GET /v1/market-brief` and
+ * surfaced on the client as {@link OilPriceAPI.getMarketBrief}.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/resources/streaming.js

@@ -5,7 +5,7 @@
  * Real-time price streaming via the OilPriceAPI ActionCable endpoint
  * (`wss://api.oilpriceapi.com/cable`).
  *
- * Streaming is a **Reservoir Mastery (Professional+)** feature. Connections
+ * Streaming is a **Professional plan ($99/mo) or higher** 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.
@@ -163,8 +163,8 @@ class PriceStreamSubscription extends node_events_1.EventEmitter {
             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."));
+            this.emit("error", new Error("WebSocket subscription rejected. Streaming requires a Professional " +
+                "plan ($99/mo) or higher and a valid API key."));
             return;
         }
         if (transportType === "disconnect") {

package/dist/cjs/resources/subscriptions.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * Agent Subscriptions ("Watches") Resource
+ *
+ * Persistent server-side "watches" that evaluate a set of commodity codes on a
+ * recurring interval and emit events an agent can poll for (OilPriceAPI #3245
+ * Phase 2). Designed for autonomous agents (MCP, schedulers, bots) that want
+ * change notifications without holding an open connection.
+ *
+ * The poll endpoint (`events`) does NOT consume the monthly request quota and
+ * has its own generous rate-limit lane, so agents can poll frequently.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubscriptionsResource = void 0;
+exports.intervalToSeconds = intervalToSeconds;
+const errors_js_1 = require("../errors.js");
+/** Default attribution source for watches created via this SDK. */
+const DEFAULT_SOURCE = "sdk-node";
+/** Named interval presets mapped to seconds. */
+const INTERVAL_PRESETS = {
+    "5m": 300,
+    "15m": 900,
+    "1h": 3600,
+    hourly: 3600,
+    daily: 86400,
+};
+/**
+ * Convert a friendly interval ("5m" / "1h" / "daily" / 300) into seconds.
+ *
+ * Accepts:
+ * - presets: "5m", "15m", "1h", "hourly", "daily"
+ * - unit expressions: "<n>s", "<n>m", "<n>h", "<n>d"
+ * - a raw number of seconds
+ *
+ * @internal Exported for unit testing of the mapping.
+ */
+function intervalToSeconds(interval) {
+    if (interval === undefined) {
+        return INTERVAL_PRESETS["5m"];
+    }
+    if (typeof interval === "number") {
+        if (!Number.isFinite(interval) || interval <= 0) {
+            throw new errors_js_1.ValidationError("interval (seconds) must be a positive number");
+        }
+        return Math.floor(interval);
+    }
+    const key = interval.trim().toLowerCase();
+    if (key in INTERVAL_PRESETS) {
+        return INTERVAL_PRESETS[key];
+    }
+    // Unit expression: <number><unit> where unit ∈ s/m/h/d.
+    const match = /^(\d+)\s*(s|m|h|d)$/.exec(key);
+    if (match) {
+        const value = parseInt(match[1], 10);
+        const unit = match[2];
+        const multipliers = { s: 1, m: 60, h: 3600, d: 86400 };
+        const seconds = value * multipliers[unit];
+        if (seconds <= 0) {
+            throw new errors_js_1.ValidationError("interval must be greater than zero");
+        }
+        return seconds;
+    }
+    throw new errors_js_1.ValidationError(`Invalid interval "${interval}". Use a preset ("5m", "15m", "1h", "daily"), ` +
+        `a unit expression ("30s", "10m", "2h", "1d"), or a number of seconds.`);
+}
+/**
+ * Agent Subscriptions ("Watches") Resource
+ *
+ * Manage persistent, recurring watches over commodity codes and poll for the
+ * events they emit.
+ *
+ * **Example:**
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Create a watch that evaluates Brent + WTI every 5 minutes
+ * const watch = await client.subscriptions.create({
+ *   name: 'Crude desk',
+ *   codes: ['BRENT_CRUDE_USD', 'WTI_USD'],
+ *   interval: '5m',
+ * });
+ *
+ * // List all watches
+ * const watches = await client.subscriptions.list();
+ *
+ * // Poll for new events
+ * let cursor = 0;
+ * const { events, cursor: next } = await client.subscriptions.events({ since: cursor });
+ * cursor = next;
+ *
+ * // Remove a watch
+ * await client.subscriptions.delete(watch.id);
+ * ```
+ */
+class SubscriptionsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all subscriptions/watches for the authenticated user.
+     *
+     * @returns Array of subscriptions, newest first.
+     *
+     * @example
+     * ```typescript
+     * const subscriptions = await client.subscriptions.list();
+     * console.log(`You have ${subscriptions.length} watches`);
+     * ```
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/subscriptions", {});
+        return Array.isArray(response) ? response : (response.subscriptions ?? []);
+    }
+    /**
+     * Create a new subscription/watch.
+     *
+     * Maps the friendly `interval` ("5m" / "1h" / "daily" / seconds) to the
+     * API's `interval_seconds`, and forwards optional attribution as
+     * `X-OPA-Source` / `X-OPA-Tool` headers (source defaults to `"sdk-node"`).
+     *
+     * @param params - Watch configuration. `codes` is required.
+     * @returns The created subscription.
+     *
+     * @throws {ValidationError} If `codes` is empty or `interval` is invalid.
+     *
+     * @example
+     * ```typescript
+     * const watch = await client.subscriptions.create({
+     *   name: 'Crude desk',
+     *   codes: ['BRENT_CRUDE_USD', 'WTI_USD'],
+     *   interval: '1h',
+     *   tool: 'my-trading-bot',
+     * });
+     * ```
+     */
+    async create(params) {
+        if (!params || !Array.isArray(params.codes) || params.codes.length === 0) {
+            throw new errors_js_1.ValidationError("codes is required and must be a non-empty array of commodity codes");
+        }
+        if (params.codes.some((c) => typeof c !== "string" || c.trim() === "")) {
+            throw new errors_js_1.ValidationError("every code must be a non-empty string");
+        }
+        const intervalSeconds = intervalToSeconds(params.interval);
+        const body = {
+            codes: params.codes,
+            interval_seconds: intervalSeconds,
+        };
+        if (params.name !== undefined) {
+            body.name = params.name;
+        }
+        if (params.deliverWebhook !== undefined) {
+            body.deliver_webhook = params.deliverWebhook;
+        }
+        const headers = {
+            "X-OPA-Source": params.source ?? DEFAULT_SOURCE,
+        };
+        if (params.tool !== undefined) {
+            headers["X-OPA-Tool"] = params.tool;
+        }
+        const response = await this.client["request"]("/v1/subscriptions", {}, { method: "POST", body, headers });
+        return "subscription" in response ? response.subscription : response;
+    }
+    /**
+     * Delete a subscription/watch.
+     *
+     * @param id - The subscription ID to delete.
+     *
+     * @throws {ValidationError} If `id` is not a non-empty string.
+     *
+     * @example
+     * ```typescript
+     * await client.subscriptions.delete(watch.id);
+     * ```
+     */
+    async delete(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Subscription ID must be a non-empty string");
+        }
+        await this.client["request"](`/v1/subscriptions/${id}`, {}, { method: "DELETE" });
+    }
+    /**
+     * Poll for events emitted by your watches.
+     *
+     * Returns events with `seq` greater than the supplied cursor, ordered
+     * ascending. This endpoint does NOT consume the monthly request quota.
+     *
+     * @param options - Cursor (`since`), optional `watchId`, and `limit`.
+     * @returns The next cursor, a `has_more` flag, and the events.
+     *
+     * @example
+     * ```typescript
+     * let cursor = 0;
+     * while (true) {
+     *   const { events, cursor: next, has_more } = await client.subscriptions.events({ since: cursor });
+     *   for (const ev of events) handle(ev);
+     *   cursor = next;
+     *   if (!has_more) break;
+     * }
+     * ```
+     */
+    async events(options = {}) {
+        const params = {};
+        if (options.since !== undefined) {
+            params.since = String(options.since);
+        }
+        if (options.watchId !== undefined) {
+            params.watch_id = options.watchId;
+        }
+        if (options.limit !== undefined) {
+            params.limit = String(options.limit);
+        }
+        return this.client["request"]("/v1/subscriptions/events", params);
+    }
+}
+exports.SubscriptionsResource = SubscriptionsResource;

package/dist/cjs/version.js

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

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import type { OilPriceAPIConfig, Price, LatestPricesOptions, HistoricalPricesOptions, Commodity, CommoditiesResponse, CategoriesResponse, DataConnectorPrice, DataConnectorOptions, DemoPricesResponse, DemoCommoditiesResponse } from "./types.js";
+import type { MarketBrief, MarketBriefOptions } from "./resources/market-brief.js";
 import { DieselResource } from "./resources/diesel.js";
 import { AlertsResource } from "./resources/alerts.js";
 import { CommoditiesResource } from "./resources/commodities.js";
@@ -17,6 +18,7 @@ import { SpreadsResource } from "./resources/spreads.js";
 import { IndicatorsResource } from "./resources/indicators.js";
 import { RawResource } from "./resources/raw.js";
 import { StreamingResource } from "./resources/streaming.js";
+import { SubscriptionsResource } from "./resources/subscriptions.js";
 /**
  * Raw HTTP response wrapper.
  *
@@ -144,9 +146,14 @@ export declare class OilPriceAPI {
     /**
      * Real-time price streaming resource (WebSocket / ActionCable).
      *
-     * Streaming requires a Reservoir Mastery (Professional+) plan.
+     * Streaming requires a Professional plan ($99/mo) or higher.
      */
     readonly stream: StreamingResource;
+    /**
+     * Agent subscriptions ("watches") resource — persistent recurring watches
+     * over commodity codes plus an event poll endpoint (#3245 Phase 2).
+     */
+    readonly subscriptions: SubscriptionsResource;
     constructor(config?: OilPriceAPIConfig);
     /**
      * Log debug messages if debug mode is enabled
@@ -311,6 +318,34 @@ export declare class OilPriceAPI {
      * ```
      */
     getCommodity(code: string): Promise<Commodity>;
+    /**
+     * Get a multi-commodity market brief (OilPriceAPI #3245 Phase 1a).
+     *
+     * Returns a structured summary (latest price, 24h change, freshness, and a
+     * 1-month forecast band) for each requested commodity, optionally with a
+     * natural-language narrative. Counts as a single request against your quota,
+     * like `/v1/prices/batch`. The per-tier cap on `codes` is enforced server-side.
+     *
+     * @param codes - Commodity codes (e.g. ["BRENT_CRUDE_USD", "WTI_USD"]). Shorthand
+     *   codes like "WTI"/"BRENT" are accepted and resolved server-side.
+     * @param options - `{ narrative }` to request the natural-language summary.
+     * @returns The structured (and optional narrative) market brief.
+     *
+     * @throws {ValidationError} If `codes` is empty.
+     *
+     * @example
+     * ```typescript
+     * const brief = await client.getMarketBrief(['BRENT_CRUDE_USD', 'WTI_USD']);
+     * for (const c of brief.commodities) {
+     *   console.log(`${c.name}: $${c.price} (${c.change_24h_pct}%)`);
+     * }
+     *
+     * // With narrative
+     * const withText = await client.getMarketBrief(['BRENT_CRUDE_USD'], { narrative: true });
+     * console.log(withText.narrative);
+     * ```
+     */
+    getMarketBrief(codes: string[], options?: MarketBriefOptions): Promise<MarketBrief>;
     /**
      * Fetch live sample prices from the public, no-auth demo endpoint.
      *

package/dist/client.js

@@ -1,4 +1,4 @@
-import { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, TimeoutError, } from "./errors.js";
+import { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, TimeoutError, ValidationError, } from "./errors.js";
 import { DieselResource } from "./resources/diesel.js";
 import { AlertsResource } from "./resources/alerts.js";
 import { CommoditiesResource } from "./resources/commodities.js";
@@ -18,6 +18,7 @@ import { SpreadsResource } from "./resources/spreads.js";
 import { IndicatorsResource } from "./resources/indicators.js";
 import { RawResource } from "./resources/raw.js";
 import { StreamingResource } from "./resources/streaming.js";
+import { SubscriptionsResource } from "./resources/subscriptions.js";
 /**
  * Official Node.js client for Oil Price API
  *
@@ -77,6 +78,7 @@ export class OilPriceAPI {
         this.indicators = new IndicatorsResource(this);
         this.raw = new RawResource(this);
         this.stream = new StreamingResource(this);
+        this.subscriptions = new SubscriptionsResource(this);
     }
     /**
      * Log debug messages if debug mode is enabled
@@ -212,6 +214,14 @@ export class OilPriceAPI {
                     if (this.appName) {
                         headers["X-App-Name"] = this.appName;
                     }
+                    // Per-request headers (e.g. MCP attribution X-OPA-Source / X-OPA-Tool).
+                    if (options?.headers) {
+                        Object.entries(options.headers).forEach(([key, value]) => {
+                            if (value !== undefined && value !== null) {
+                                headers[key] = value;
+                            }
+                        });
+                    }
                     const fetchOptions = {
                         method: options?.method || "GET",
                         headers,
@@ -521,6 +531,45 @@ export class OilPriceAPI {
     async getCommodity(code) {
         return this.request(`/v1/commodities/${code}`, {});
     }
+    /**
+     * Get a multi-commodity market brief (OilPriceAPI #3245 Phase 1a).
+     *
+     * Returns a structured summary (latest price, 24h change, freshness, and a
+     * 1-month forecast band) for each requested commodity, optionally with a
+     * natural-language narrative. Counts as a single request against your quota,
+     * like `/v1/prices/batch`. The per-tier cap on `codes` is enforced server-side.
+     *
+     * @param codes - Commodity codes (e.g. ["BRENT_CRUDE_USD", "WTI_USD"]). Shorthand
+     *   codes like "WTI"/"BRENT" are accepted and resolved server-side.
+     * @param options - `{ narrative }` to request the natural-language summary.
+     * @returns The structured (and optional narrative) market brief.
+     *
+     * @throws {ValidationError} If `codes` is empty.
+     *
+     * @example
+     * ```typescript
+     * const brief = await client.getMarketBrief(['BRENT_CRUDE_USD', 'WTI_USD']);
+     * for (const c of brief.commodities) {
+     *   console.log(`${c.name}: $${c.price} (${c.change_24h_pct}%)`);
+     * }
+     *
+     * // With narrative
+     * const withText = await client.getMarketBrief(['BRENT_CRUDE_USD'], { narrative: true });
+     * console.log(withText.narrative);
+     * ```
+     */
+    async getMarketBrief(codes, options) {
+        if (!Array.isArray(codes) || codes.length === 0) {
+            throw new ValidationError("codes is required and must be a non-empty array of commodity codes");
+        }
+        const params = {
+            codes: codes.join(","),
+        };
+        if (options?.narrative) {
+            params.narrative = "true";
+        }
+        return this.request("/v1/market-brief", params);
+    }
     /**
      * Fetch live sample prices from the public, no-auth demo endpoint.
      *

package/dist/index.d.ts

@@ -26,6 +26,9 @@ export type { MonthlyForecast, ForecastAccuracy, ArchivedForecast } from "./reso
 export type { DataQualitySummary, DataQualityReportMeta, DataQualityReport, } from "./resources/data-quality.js";
 export type { DrillingIntelligenceData, LatestDrillingData, DrillingSummary, DrillingTrend, FracSpreadData, WellPermitData, DUCWellData, CompletionData, WellsDrilledData, BasinDrillingData, } from "./resources/drilling.js";
 export type { WellTimelineEvent, WellTimeline, RigCountRecord, RigCountByBasin, RigCountByState, HistoricalRigCount, OilInventoryRecord, OilInventorySummary, InventoryByProduct, HistoricalInventory, CushingInventory, OPECProductionRecord, TotalOPECProduction, ProductionByCountry, HistoricalProduction, TopProducer, DrillingProductivityRecord, DrillingProductivitySummary, DUCWellInventory, ProductivityByBasin, HistoricalProductivity, ProductivityTrend, ForecastRecord, ForecastSummary, PriceForecast, ProductionForecast, HistoricalForecast, ForecastComparison, WellPermitRecord, WellPermitSummary, PermitsByState, PermitsByOperator, PermitsByFormation, WellPermitSearchQuery, FracFocusRecord, FracFocusSummary, DisclosuresByState, DisclosuresByOperator, ChemicalUsage, WellChemical, FracFocusSearchQuery, } from "./resources/ei/index.js";
+export type { MarketBrief, MarketBriefCommodity, MarketBriefForecast, MarketBriefOptions, } from "./resources/market-brief.js";
+export type { Subscription, SubscriptionStatus, SubscriptionSource, SubscriptionInterval, CreateSubscriptionParams, SubscriptionEvent, SubscriptionEventsResult, SubscriptionEventsOptions, } from "./resources/subscriptions.js";
+export { SubscriptionsResource, intervalToSeconds } from "./resources/subscriptions.js";
 export type { WebhookEndpoint, CreateWebhookParams, UpdateWebhookParams, WebhookTestResponse as WebhookTestResult, WebhookEvent, } from "./resources/webhooks.js";
 export type { DataSourceType, DataSourceStatus, DataSource, CreateDataSourceParams, UpdateDataSourceParams, DataSourceTestResponse, DataSourceLog, DataSourceHealth, CredentialRotationResponse, } from "./resources/data-sources.js";
 export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, ValidationError, TimeoutError, } from "./errors.js";

package/dist/index.js

@@ -12,6 +12,7 @@ export { FUTURES_CONTRACTS, FUTURES_FAMILY_SLUGS, FuturesContractFamily, } from
 export { SpreadsResource } from "./resources/spreads.js";
 export { IndicatorsResource } from "./resources/indicators.js";
 export { RawResource } from "./resources/raw.js";
+export { SubscriptionsResource, intervalToSeconds } from "./resources/subscriptions.js";
 export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, ValidationError, TimeoutError, } from "./errors.js";
 export { DieselResource } from "./resources/diesel.js";
 export { AlertsResource } from "./resources/alerts.js";

package/dist/resources/market-brief.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Market Brief types (OilPriceAPI #3245 Phase 1a)
+ *
+ * A multi-commodity structured (+ optional narrative) market summary composed
+ * from existing price + forecast data. Served by `GET /v1/market-brief` and
+ * surfaced on the client as {@link OilPriceAPI.getMarketBrief}.
+ */
+/**
+ * Short-horizon (1-month) point forecast for a commodity in a market brief.
+ */
+export interface MarketBriefForecast {
+    /** Central point estimate. */
+    point: number;
+    /** Low end of the forecast band. */
+    low: number;
+    /** High end of the forecast band. */
+    high: number;
+    /** Model confidence label (e.g. "low", "medium", "high"). */
+    confidence: string;
+}
+/**
+ * One commodity's slice of a market brief.
+ */
+export interface MarketBriefCommodity {
+    /** Commodity code (e.g. "BRENT_CRUDE_USD"). */
+    code: string;
+    /** Human-readable commodity name. */
+    name: string;
+    /** Latest price. */
+    price: number;
+    /** ISO currency code (e.g. "USD"). */
+    currency: string;
+    /** Price unit (e.g. "barrel"). */
+    unit: string;
+    /** 24h percentage change. */
+    change_24h_pct: number;
+    /** 24h absolute change. */
+    change_24h_abs: number;
+    /** ISO timestamp the price was observed. */
+    as_of: string;
+    /** Upstream data source. */
+    source: string;
+    /** True when the price is stale (no fresh update). */
+    stale: boolean;
+    /** 1-month forecast band, when available. */
+    forecast_1m: MarketBriefForecast | null;
+}
+/**
+ * A multi-commodity market brief.
+ *
+ * Returned by {@link OilPriceAPI.getMarketBrief}.
+ */
+export interface MarketBrief {
+    /** ISO timestamp the brief was generated. */
+    as_of: string;
+    /** The (resolved, canonical) codes included in the brief. */
+    codes: string[];
+    /** Per-commodity structured summary. */
+    commodities: MarketBriefCommodity[];
+    /** Optional natural-language narrative (only when `narrative: true`). */
+    narrative?: string;
+}
+/**
+ * Options for {@link OilPriceAPI.getMarketBrief}.
+ */
+export interface MarketBriefOptions {
+    /**
+     * Request a natural-language narrative alongside the structured data.
+     * Defaults to `false`.
+     */
+    narrative?: boolean;
+}

package/dist/resources/market-brief.js

@@ -0,0 +1,8 @@
+/**
+ * Market Brief types (OilPriceAPI #3245 Phase 1a)
+ *
+ * A multi-commodity structured (+ optional narrative) market summary composed
+ * from existing price + forecast data. Served by `GET /v1/market-brief` and
+ * surfaced on the client as {@link OilPriceAPI.getMarketBrief}.
+ */
+export {};

package/dist/resources/streaming.d.ts

@@ -4,7 +4,7 @@
  * Real-time price streaming via the OilPriceAPI ActionCable endpoint
  * (`wss://api.oilpriceapi.com/cable`).
  *
- * Streaming is a **Reservoir Mastery (Professional+)** feature. Connections
+ * Streaming is a **Professional plan ($99/mo) or higher** 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.
@@ -105,7 +105,7 @@ export interface WelcomeMessage {
     };
 }
 /**
- * Rig-count update broadcast (drilling / Reservoir Mastery accounts).
+ * Rig-count update broadcast (drilling / Professional+ accounts).
  */
 export interface RigCountUpdateMessage {
     type: "rig_count_update";

package/dist/resources/streaming.js

@@ -4,7 +4,7 @@
  * Real-time price streaming via the OilPriceAPI ActionCable endpoint
  * (`wss://api.oilpriceapi.com/cable`).
  *
- * Streaming is a **Reservoir Mastery (Professional+)** feature. Connections
+ * Streaming is a **Professional plan ($99/mo) or higher** 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.
@@ -157,8 +157,8 @@ export class PriceStreamSubscription extends EventEmitter {
             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."));
+            this.emit("error", new Error("WebSocket subscription rejected. Streaming requires a Professional " +
+                "plan ($99/mo) or higher and a valid API key."));
             return;
         }
         if (transportType === "disconnect") {

package/dist/resources/subscriptions.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Agent Subscriptions ("Watches") Resource
+ *
+ * Persistent server-side "watches" that evaluate a set of commodity codes on a
+ * recurring interval and emit events an agent can poll for (OilPriceAPI #3245
+ * Phase 2). Designed for autonomous agents (MCP, schedulers, bots) that want
+ * change notifications without holding an open connection.
+ *
+ * The poll endpoint (`events`) does NOT consume the monthly request quota and
+ * has its own generous rate-limit lane, so agents can poll frequently.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Lifecycle status of a subscription/watch.
+ */
+export type SubscriptionStatus = "active" | "paused";
+/**
+ * Attribution source recorded on a watch. Defaults to `"sdk-node"` when created
+ * via this SDK. The API canonicalizes unknown values to `"api"`.
+ */
+export type SubscriptionSource = string;
+/**
+ * A persistent agent subscription ("watch").
+ *
+ * Returned by {@link SubscriptionsResource.list} and
+ * {@link SubscriptionsResource.create}.
+ */
+export interface Subscription {
+    /** Unique watch identifier (UUID). */
+    id: string;
+    /** User-friendly watch name. */
+    name: string | null;
+    /** Commodity codes this watch evaluates (e.g. ["BRENT_CRUDE_USD"]). */
+    codes: string[];
+    /** Evaluation cadence in seconds. */
+    interval_seconds: number;
+    /** Lifecycle status. */
+    status: SubscriptionStatus;
+    /** Whether matching events are also delivered via webhook. */
+    deliver_webhook: boolean;
+    /** Attribution source (e.g. "sdk-node", "mcp", "api"). */
+    source: string;
+    /** Attribution tool name, if any. */
+    tool_name: string | null;
+    /** ISO timestamp the watch was last evaluated, or null. */
+    last_evaluated_at: string | null;
+    /** ISO timestamp the watch is next scheduled to run, or null. */
+    next_run_at: string | null;
+    /** ISO timestamp when the watch was created. */
+    created_at: string;
+}
+/**
+ * A friendly interval expression accepted by {@link SubscriptionsResource.create}.
+ *
+ * Either a preset string ("5m", "15m", "1h", "daily") or an explicit number of
+ * seconds.
+ */
+export type SubscriptionInterval = "5m" | "15m" | "1h" | "daily" | (string & {}) | number;
+/**
+ * Parameters for creating a new subscription/watch.
+ */
+export interface CreateSubscriptionParams {
+    /** Commodity codes to watch (e.g. ["BRENT_CRUDE_USD", "WTI_USD"]). Required. */
+    codes: string[];
+    /**
+     * Evaluation cadence. A friendly preset ("5m" / "15m" / "1h" / "daily"), a
+     * `<n>m` / `<n>h` / `<n>d` / `<n>s` expression, or a number of seconds.
+     * Defaults to "5m" when omitted.
+     */
+    interval?: SubscriptionInterval;
+    /** Optional friendly watch name. */
+    name?: string;
+    /** Whether to also deliver matching events via webhook. */
+    deliverWebhook?: boolean;
+    /**
+     * Attribution source → `X-OPA-Source` header. Defaults to `"sdk-node"`.
+     */
+    source?: string;
+    /** Attribution tool name → `X-OPA-Tool` header. */
+    tool?: string;
+}
+/**
+ * A single event emitted by a watch evaluation.
+ *
+ * The exact payload depends on the event type; common fields are surfaced here
+ * while the full server payload is preserved via the index signature.
+ */
+export interface SubscriptionEvent {
+    /** Monotonic per-user sequence number; use as the `since` cursor. */
+    seq: number;
+    /** The watch that produced this event. */
+    watch_id: string;
+    /** Event type (e.g. "evaluated", "threshold_crossed"). */
+    type?: string;
+    /** Commodity code the event concerns, if applicable. */
+    code?: string;
+    /** ISO timestamp the event was emitted. */
+    created_at?: string;
+    /** Any additional server-provided fields. */
+    [key: string]: unknown;
+}
+/**
+ * Response from {@link SubscriptionsResource.events}.
+ */
+export interface SubscriptionEventsResult {
+    /** The highest `seq` returned; pass as `since` on the next poll. */
+    cursor: number;
+    /** True if more events are available beyond this page. */
+    has_more: boolean;
+    /** Events with `seq > since`, ordered ascending by `seq`. */
+    events: SubscriptionEvent[];
+}
+/**
+ * Options for {@link SubscriptionsResource.events}.
+ */
+export interface SubscriptionEventsOptions {
+    /** Return only events with `seq` greater than this cursor. Defaults to 0. */
+    since?: number;
+    /** Restrict to a single watch by id. */
+    watchId?: string;
+    /** Max events to return (1-500, server default 100). */
+    limit?: number;
+}
+/**
+ * Convert a friendly interval ("5m" / "1h" / "daily" / 300) into seconds.
+ *
+ * Accepts:
+ * - presets: "5m", "15m", "1h", "hourly", "daily"
+ * - unit expressions: "<n>s", "<n>m", "<n>h", "<n>d"
+ * - a raw number of seconds
+ *
+ * @internal Exported for unit testing of the mapping.
+ */
+export declare function intervalToSeconds(interval: SubscriptionInterval | undefined): number;
+/**
+ * Agent Subscriptions ("Watches") Resource
+ *
+ * Manage persistent, recurring watches over commodity codes and poll for the
+ * events they emit.
+ *
+ * **Example:**
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Create a watch that evaluates Brent + WTI every 5 minutes
+ * const watch = await client.subscriptions.create({
+ *   name: 'Crude desk',
+ *   codes: ['BRENT_CRUDE_USD', 'WTI_USD'],
+ *   interval: '5m',
+ * });
+ *
+ * // List all watches
+ * const watches = await client.subscriptions.list();
+ *
+ * // Poll for new events
+ * let cursor = 0;
+ * const { events, cursor: next } = await client.subscriptions.events({ since: cursor });
+ * cursor = next;
+ *
+ * // Remove a watch
+ * await client.subscriptions.delete(watch.id);
+ * ```
+ */
+export declare class SubscriptionsResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * List all subscriptions/watches for the authenticated user.
+     *
+     * @returns Array of subscriptions, newest first.
+     *
+     * @example
+     * ```typescript
+     * const subscriptions = await client.subscriptions.list();
+     * console.log(`You have ${subscriptions.length} watches`);
+     * ```
+     */
+    list(): Promise<Subscription[]>;
+    /**
+     * Create a new subscription/watch.
+     *
+     * Maps the friendly `interval` ("5m" / "1h" / "daily" / seconds) to the
+     * API's `interval_seconds`, and forwards optional attribution as
+     * `X-OPA-Source` / `X-OPA-Tool` headers (source defaults to `"sdk-node"`).
+     *
+     * @param params - Watch configuration. `codes` is required.
+     * @returns The created subscription.
+     *
+     * @throws {ValidationError} If `codes` is empty or `interval` is invalid.
+     *
+     * @example
+     * ```typescript
+     * const watch = await client.subscriptions.create({
+     *   name: 'Crude desk',
+     *   codes: ['BRENT_CRUDE_USD', 'WTI_USD'],
+     *   interval: '1h',
+     *   tool: 'my-trading-bot',
+     * });
+     * ```
+     */
+    create(params: CreateSubscriptionParams): Promise<Subscription>;
+    /**
+     * Delete a subscription/watch.
+     *
+     * @param id - The subscription ID to delete.
+     *
+     * @throws {ValidationError} If `id` is not a non-empty string.
+     *
+     * @example
+     * ```typescript
+     * await client.subscriptions.delete(watch.id);
+     * ```
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Poll for events emitted by your watches.
+     *
+     * Returns events with `seq` greater than the supplied cursor, ordered
+     * ascending. This endpoint does NOT consume the monthly request quota.
+     *
+     * @param options - Cursor (`since`), optional `watchId`, and `limit`.
+     * @returns The next cursor, a `has_more` flag, and the events.
+     *
+     * @example
+     * ```typescript
+     * let cursor = 0;
+     * while (true) {
+     *   const { events, cursor: next, has_more } = await client.subscriptions.events({ since: cursor });
+     *   for (const ev of events) handle(ev);
+     *   cursor = next;
+     *   if (!has_more) break;
+     * }
+     * ```
+     */
+    events(options?: SubscriptionEventsOptions): Promise<SubscriptionEventsResult>;
+}

package/dist/resources/subscriptions.js

@@ -0,0 +1,212 @@
+/**
+ * Agent Subscriptions ("Watches") Resource
+ *
+ * Persistent server-side "watches" that evaluate a set of commodity codes on a
+ * recurring interval and emit events an agent can poll for (OilPriceAPI #3245
+ * Phase 2). Designed for autonomous agents (MCP, schedulers, bots) that want
+ * change notifications without holding an open connection.
+ *
+ * The poll endpoint (`events`) does NOT consume the monthly request quota and
+ * has its own generous rate-limit lane, so agents can poll frequently.
+ */
+import { ValidationError } from "../errors.js";
+/** Default attribution source for watches created via this SDK. */
+const DEFAULT_SOURCE = "sdk-node";
+/** Named interval presets mapped to seconds. */
+const INTERVAL_PRESETS = {
+    "5m": 300,
+    "15m": 900,
+    "1h": 3600,
+    hourly: 3600,
+    daily: 86400,
+};
+/**
+ * Convert a friendly interval ("5m" / "1h" / "daily" / 300) into seconds.
+ *
+ * Accepts:
+ * - presets: "5m", "15m", "1h", "hourly", "daily"
+ * - unit expressions: "<n>s", "<n>m", "<n>h", "<n>d"
+ * - a raw number of seconds
+ *
+ * @internal Exported for unit testing of the mapping.
+ */
+export function intervalToSeconds(interval) {
+    if (interval === undefined) {
+        return INTERVAL_PRESETS["5m"];
+    }
+    if (typeof interval === "number") {
+        if (!Number.isFinite(interval) || interval <= 0) {
+            throw new ValidationError("interval (seconds) must be a positive number");
+        }
+        return Math.floor(interval);
+    }
+    const key = interval.trim().toLowerCase();
+    if (key in INTERVAL_PRESETS) {
+        return INTERVAL_PRESETS[key];
+    }
+    // Unit expression: <number><unit> where unit ∈ s/m/h/d.
+    const match = /^(\d+)\s*(s|m|h|d)$/.exec(key);
+    if (match) {
+        const value = parseInt(match[1], 10);
+        const unit = match[2];
+        const multipliers = { s: 1, m: 60, h: 3600, d: 86400 };
+        const seconds = value * multipliers[unit];
+        if (seconds <= 0) {
+            throw new ValidationError("interval must be greater than zero");
+        }
+        return seconds;
+    }
+    throw new ValidationError(`Invalid interval "${interval}". Use a preset ("5m", "15m", "1h", "daily"), ` +
+        `a unit expression ("30s", "10m", "2h", "1d"), or a number of seconds.`);
+}
+/**
+ * Agent Subscriptions ("Watches") Resource
+ *
+ * Manage persistent, recurring watches over commodity codes and poll for the
+ * events they emit.
+ *
+ * **Example:**
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Create a watch that evaluates Brent + WTI every 5 minutes
+ * const watch = await client.subscriptions.create({
+ *   name: 'Crude desk',
+ *   codes: ['BRENT_CRUDE_USD', 'WTI_USD'],
+ *   interval: '5m',
+ * });
+ *
+ * // List all watches
+ * const watches = await client.subscriptions.list();
+ *
+ * // Poll for new events
+ * let cursor = 0;
+ * const { events, cursor: next } = await client.subscriptions.events({ since: cursor });
+ * cursor = next;
+ *
+ * // Remove a watch
+ * await client.subscriptions.delete(watch.id);
+ * ```
+ */
+export class SubscriptionsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all subscriptions/watches for the authenticated user.
+     *
+     * @returns Array of subscriptions, newest first.
+     *
+     * @example
+     * ```typescript
+     * const subscriptions = await client.subscriptions.list();
+     * console.log(`You have ${subscriptions.length} watches`);
+     * ```
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/subscriptions", {});
+        return Array.isArray(response) ? response : (response.subscriptions ?? []);
+    }
+    /**
+     * Create a new subscription/watch.
+     *
+     * Maps the friendly `interval` ("5m" / "1h" / "daily" / seconds) to the
+     * API's `interval_seconds`, and forwards optional attribution as
+     * `X-OPA-Source` / `X-OPA-Tool` headers (source defaults to `"sdk-node"`).
+     *
+     * @param params - Watch configuration. `codes` is required.
+     * @returns The created subscription.
+     *
+     * @throws {ValidationError} If `codes` is empty or `interval` is invalid.
+     *
+     * @example
+     * ```typescript
+     * const watch = await client.subscriptions.create({
+     *   name: 'Crude desk',
+     *   codes: ['BRENT_CRUDE_USD', 'WTI_USD'],
+     *   interval: '1h',
+     *   tool: 'my-trading-bot',
+     * });
+     * ```
+     */
+    async create(params) {
+        if (!params || !Array.isArray(params.codes) || params.codes.length === 0) {
+            throw new ValidationError("codes is required and must be a non-empty array of commodity codes");
+        }
+        if (params.codes.some((c) => typeof c !== "string" || c.trim() === "")) {
+            throw new ValidationError("every code must be a non-empty string");
+        }
+        const intervalSeconds = intervalToSeconds(params.interval);
+        const body = {
+            codes: params.codes,
+            interval_seconds: intervalSeconds,
+        };
+        if (params.name !== undefined) {
+            body.name = params.name;
+        }
+        if (params.deliverWebhook !== undefined) {
+            body.deliver_webhook = params.deliverWebhook;
+        }
+        const headers = {
+            "X-OPA-Source": params.source ?? DEFAULT_SOURCE,
+        };
+        if (params.tool !== undefined) {
+            headers["X-OPA-Tool"] = params.tool;
+        }
+        const response = await this.client["request"]("/v1/subscriptions", {}, { method: "POST", body, headers });
+        return "subscription" in response ? response.subscription : response;
+    }
+    /**
+     * Delete a subscription/watch.
+     *
+     * @param id - The subscription ID to delete.
+     *
+     * @throws {ValidationError} If `id` is not a non-empty string.
+     *
+     * @example
+     * ```typescript
+     * await client.subscriptions.delete(watch.id);
+     * ```
+     */
+    async delete(id) {
+        if (!id || typeof id !== "string") {
+            throw new ValidationError("Subscription ID must be a non-empty string");
+        }
+        await this.client["request"](`/v1/subscriptions/${id}`, {}, { method: "DELETE" });
+    }
+    /**
+     * Poll for events emitted by your watches.
+     *
+     * Returns events with `seq` greater than the supplied cursor, ordered
+     * ascending. This endpoint does NOT consume the monthly request quota.
+     *
+     * @param options - Cursor (`since`), optional `watchId`, and `limit`.
+     * @returns The next cursor, a `has_more` flag, and the events.
+     *
+     * @example
+     * ```typescript
+     * let cursor = 0;
+     * while (true) {
+     *   const { events, cursor: next, has_more } = await client.subscriptions.events({ since: cursor });
+     *   for (const ev of events) handle(ev);
+     *   cursor = next;
+     *   if (!has_more) break;
+     * }
+     * ```
+     */
+    async events(options = {}) {
+        const params = {};
+        if (options.since !== undefined) {
+            params.since = String(options.since);
+        }
+        if (options.watchId !== undefined) {
+            params.watch_id = options.watchId;
+        }
+        if (options.limit !== undefined) {
+            params.limit = String(options.limit);
+        }
+        return this.client["request"]("/v1/subscriptions/events", params);
+    }
+}

package/dist/version.d.ts

@@ -7,7 +7,7 @@
  * - X-Client-Version header
  * - Package.json (should match)
  */
-export declare const SDK_VERSION = "0.9.1";
+export declare const SDK_VERSION = "0.10.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.9.1";
+export const SDK_VERSION = "0.10.0";
 /**
  * SDK identifier used in User-Agent and X-Api-Client headers
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oilpriceapi",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Official Node.js SDK for Oil Price API - Real-time and historical oil & commodity prices",
   "type": "module",
   "main": "./dist/cjs/index.js",