oilpriceapi 0.9.0 → 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/futures.js

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FuturesResource = exports.FuturesContractFamily = exports.FUTURES_FAMILY_SLUGS = exports.FUTURES_CONTRACTS = void 0;
+exports.resolveFuturesFamilySlug = resolveFuturesFamilySlug;
 const errors_js_1 = require("../errors.js");
 /**
  * Ergonomic contract codes for the most-requested futures families (issue #1).
@@ -48,15 +49,34 @@ exports.FUTURES_CONTRACTS = {
  * path segment used by the typed family helpers.
  */
 exports.FUTURES_FAMILY_SLUGS = {
-    [exports.FUTURES_CONTRACTS.BRENT]: "ice-brent",
-    [exports.FUTURES_CONTRACTS.WTI]: "ice-wti",
-    [exports.FUTURES_CONTRACTS.GASOIL]: "ice-gasoil",
-    [exports.FUTURES_CONTRACTS.NATURAL_GAS]: "natural-gas",
-    [exports.FUTURES_CONTRACTS.TTF_GAS]: "ttf-gas",
-    [exports.FUTURES_CONTRACTS.LNG_JKM]: "lng-jkm",
-    [exports.FUTURES_CONTRACTS.EUA_CARBON]: "eua-carbon",
-    [exports.FUTURES_CONTRACTS.UK_CARBON]: "uk-carbon",
+    [exports.FUTURES_CONTRACTS.BRENT]: "ice-brent", // BZ
+    [exports.FUTURES_CONTRACTS.WTI]: "ice-wti", // CL
+    [exports.FUTURES_CONTRACTS.GASOIL]: "ice-gasoil", // G
+    QS: "ice-gasoil", // ICE Gasoil also trades under the QS ticker prefix
+    [exports.FUTURES_CONTRACTS.NATURAL_GAS]: "natural-gas", // NG
+    [exports.FUTURES_CONTRACTS.TTF_GAS]: "ttf-gas", // TTF
+    [exports.FUTURES_CONTRACTS.LNG_JKM]: "lng-jkm", // JKM
+    [exports.FUTURES_CONTRACTS.EUA_CARBON]: "eua-carbon", // EUA
+    [exports.FUTURES_CONTRACTS.UK_CARBON]: "uk-carbon", // UKA
 };
+/**
+ * Resolve a futures contract code (e.g. `"BZ"`, `"QS"`) or an already-valid
+ * family slug (e.g. `"ice-brent"`) to its `/v1/futures/{slug}` path segment.
+ *
+ * Matching is case-insensitive for codes. Returns `null` if the input maps to
+ * neither a known code nor a known family slug.
+ */
+function resolveFuturesFamilySlug(codeOrSlug) {
+    const trimmed = codeOrSlug.trim();
+    // Direct code match (case-insensitive — codes are upper-case).
+    const byCode = exports.FUTURES_FAMILY_SLUGS[trimmed.toUpperCase()];
+    if (byCode)
+        return byCode;
+    // Already a valid family slug?
+    const lower = trimmed.toLowerCase();
+    const isSlug = Object.values(exports.FUTURES_FAMILY_SLUGS).includes(lower);
+    return isSlug ? lower : null;
+}
 /**
  * Typed helper for a single futures contract family (e.g., ICE Brent, Gasoil).
  *
@@ -80,9 +100,12 @@ class FuturesContractFamily {
     }
     /**
      * Get the latest price for this contract family.
+     *
+     * Latest is served from the bare slug path `GET /v1/futures/{slug}` —
+     * there is NO `/latest` suffix (that path 404s).
      */
     async latest() {
-        return this.client["request"](`/v1/futures/${this.slug}/latest`, {});
+        return this.client["request"](`/v1/futures/${this.slug}`, {});
     }
     /**
      * Get historical prices for this contract family.
@@ -156,16 +179,13 @@ exports.FuturesContractFamily = FuturesContractFamily;
  *
  * const client = new OilPriceAPI({ apiKey: 'your_key' });
  *
- * // Get latest price
- * const latest = await client.futures.latest('CL.1');
+ * // Get the latest curve by contract code (resolves to GET /v1/futures/ice-wti)
+ * const latest = await client.futures.latest('CL');
  * console.log(`${latest.contract}: $${latest.price}`);
  *
- * // Get OHLC data
- * const ohlc = await client.futures.ohlc('CL.1', '2024-01-15');
- * console.log(`High: $${ohlc.high}, Low: $${ohlc.low}`);
- *
- * // Get futures curve
- * const curve = await client.futures.curve('CL');
+ * // Typed family helpers are the most ergonomic option:
+ * const brent = await client.futures.brent().latest();
+ * const curve = await client.futures.brent().curve();
  * curve.curve.forEach(point => {
  *   console.log(`${point.months_out}mo: $${point.price}`);
  * });
@@ -176,25 +196,42 @@ class FuturesResource {
         this.client = client;
     }
     /**
-     * Get latest price for a futures contract
+     * Get the latest curve/quote for a futures contract family.
      *
-     * @param contract - Contract symbol (e.g., "CL.1", "BZ.2")
-     * @returns Latest futures price data
+     * Accepts an ergonomic contract code (e.g. `"BZ"`, `"CL"`, `"QS"`) or a
+     * family slug (e.g. `"ice-brent"`). The code is resolved to its family slug
+     * and the request is sent to `GET /v1/futures/{slug}` — the bare slug path,
+     * with NO `/latest` suffix (the suffixed path 404s).
      *
-     * @throws {NotFoundError} If contract not found
+     * Supported codes: BZ (Brent), CL (WTI), G/QS (Gasoil), NG (Natural Gas),
+     * TTF, JKM, EUA, UKA. Slugs: ice-brent, ice-wti, ice-gasoil, natural-gas,
+     * ttf-gas, lng-jkm, eua-carbon, uk-carbon.
+     *
+     * @param contract - Contract code (e.g. "BZ") or family slug (e.g. "ice-brent").
+     * @returns Latest futures price/curve data
+     *
+     * @throws {ValidationError} If the code/slug is empty or unrecognized.
      * @throws {OilPriceAPIError} If API request fails
      *
      * @example
      * ```typescript
-     * const price = await client.futures.latest('CL.1');
-     * console.log(`WTI Front Month: $${price.price}`);
+     * import { FUTURES_CONTRACTS } from 'oilpriceapi';
+     * const price = await client.futures.latest(FUTURES_CONTRACTS.BRENT); // "BZ"
+     * const wti = await client.futures.latest('ice-wti');
      * ```
      */
     async latest(contract) {
         if (!contract || typeof contract !== "string") {
             throw new errors_js_1.ValidationError("Contract symbol must be a non-empty string");
         }
-        return this.client["request"](`/v1/futures/${contract}`, {});
+        const slug = resolveFuturesFamilySlug(contract);
+        if (!slug) {
+            throw new errors_js_1.ValidationError(`Unknown futures contract "${contract}". Use a contract code ` +
+                `(BZ, CL, G, QS, NG, TTF, JKM, EUA, UKA) or a family slug ` +
+                `(ice-brent, ice-wti, ice-gasoil, natural-gas, ttf-gas, lng-jkm, ` +
+                `eua-carbon, uk-carbon).`);
+        }
+        return this.client["request"](`/v1/futures/${slug}`, {});
     }
     /**
      * Get historical prices for a futures contract

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.0";
+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.
      *