oilpriceapi 0.9.0 → 0.10.0

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/futures.d.ts

@@ -6,23 +6,71 @@
  */
 import type { OilPriceAPI } from "../client.js";
 /**
- * Futures contract price data
+ * A single futures contract month within a {@link FuturesPrice} response.
+ *
+ * Returned at the top level under `front_month` and for every entry in
+ * `contracts[]`. The latest traded price is `last_price`.
+ */
+export interface FuturesContractMonth {
+    /** Contract code (e.g. "BRENT_FUTURES_2026_08"). */
+    code?: string;
+    /** Contract month in YYYY-MM form (e.g. "2026-08"). */
+    contract_month?: string;
+    /** Latest traded/settlement price for this contract month. */
+    last_price?: number;
+    /** Currency code (e.g. "USD"). */
+    currency?: string;
+    /** Opening price (may be returned as a string by the API). */
+    open?: number | string;
+    /** Closing price (may be returned as a string by the API). */
+    close?: number | string;
+    /** Session high. */
+    high?: number | string;
+    /** Session low. */
+    low?: number | string;
+    /** Any additional fields the API returns for a contract month. */
+    [key: string]: unknown;
+}
+/**
+ * Futures contract price data.
+ *
+ * `GET /v1/futures/{slug}` returns a TOP-LEVEL object (there is NO
+ * `{ status, data }` envelope). The latest price lives at
+ * `front_month.last_price`, with the full term structure in `contracts[]`.
+ *
+ * Legacy flat fields (`contract`, `price`, `currency`, `timestamp`) are kept
+ * optional for backward compatibility, but real responses populate
+ * `front_month` / `contracts` instead.
  */
 export interface FuturesPrice {
-    /** Contract symbol */
-    contract: string;
-    /** Current price */
-    price: number;
-    /** Formatted price string */
+    /** Commodity identifier (e.g. "BRENT_FUTURES"). */
+    commodity?: string;
+    /** Data source (e.g. "ICE"). */
+    source?: string;
+    /** ISO timestamp the data was last updated. */
+    updated_at?: string;
+    /** Settlement date for the prices. */
+    settlement_date?: string;
+    /** Front-month contract — the latest price is `front_month.last_price`. */
+    front_month?: FuturesContractMonth;
+    /** Full forward term structure, one entry per contract month. */
+    contracts?: FuturesContractMonth[];
+    /** Optional warning when the returned data is stale. */
+    data_age_warning?: unknown;
+    /** Additional metadata returned by the API. */
+    metadata?: Record<string, unknown>;
+    /** @deprecated Legacy flat contract symbol — use `front_month.code`. */
+    contract?: string;
+    /** @deprecated Legacy flat price — use `front_month.last_price`. */
+    price?: number;
+    /** @deprecated Legacy formatted price string. */
     formatted?: string;
-    /** Currency code */
-    currency: string;
-    /** Contract expiration date */
+    /** @deprecated Legacy currency — use `front_month.currency`. */
+    currency?: string;
+    /** @deprecated Legacy contract expiration date. */
     expiration?: string;
-    /** ISO timestamp when price was recorded */
-    timestamp: string;
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
+    /** @deprecated Legacy ISO timestamp — use `updated_at`. */
+    timestamp?: string;
 }
 /**
  * Historical futures price data
@@ -141,15 +189,25 @@ export interface FuturesCurvePoint {
     contract?: string;
 }
 /**
- * Futures curve data
+ * Futures curve data.
+ *
+ * `GET /v1/futures/{slug}/curve` can legitimately return a no-data response of
+ * the form `{ error: "No futures data available for curve analysis", date }`
+ * when a curve cannot be built. That is a valid state (not an HTTP error), so
+ * `curve` is optional and `error` / `date` are surfaced for callers to detect
+ * the no-data case.
  */
 export interface FuturesCurveData {
     /** Base contract */
-    contract: string;
+    contract?: string;
     /** ISO timestamp when curve was generated */
-    timestamp: string;
-    /** Array of curve points */
-    curve: FuturesCurvePoint[];
+    timestamp?: string;
+    /** Array of curve points (absent in the no-data response) */
+    curve?: FuturesCurvePoint[];
+    /** Present in the no-data response: "No futures data available for curve analysis". */
+    error?: string;
+    /** Date associated with the no-data response. */
+    date?: string;
 }
 /**
  * Continuous contract data point
@@ -196,9 +254,10 @@ export interface FuturesSpreadHistory {
 /**
  * Slugs for the supported ICE / gas / carbon futures contract families.
  *
- * These map to the `GET /v1/futures/{slug}/...` endpoints. Each family
- * supports `/latest`, `/historical`, `/ohlc`, `/intraday`, `/spreads`,
- * `/curve`, and `/spread-history`.
+ * These map to the `GET /v1/futures/{slug}` (latest) endpoint plus the
+ * `GET /v1/futures/{slug}/...` sub-resources. Latest is the bare slug path
+ * (there is NO `/latest` suffix). Each family also supports `/historical`,
+ * `/ohlc`, `/intraday`, `/spreads`, `/curve`, and `/spread-history`.
  */
 export type FuturesContractFamilySlug = "ice-brent" | "ice-gasoil" | "ice-wti" | "natural-gas" | "ttf-gas" | "lng-jkm" | "eua-carbon" | "uk-carbon";
 /**
@@ -241,6 +300,14 @@ export declare const FUTURES_CONTRACTS: {
  * path segment used by the typed family helpers.
  */
 export declare const FUTURES_FAMILY_SLUGS: Record<string, FuturesContractFamilySlug>;
+/**
+ * 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.
+ */
+export declare function resolveFuturesFamilySlug(codeOrSlug: string): FuturesContractFamilySlug | null;
 /**
  * Typed helper for a single futures contract family (e.g., ICE Brent, Gasoil).
  *
@@ -264,6 +331,9 @@ export declare class FuturesContractFamily {
     slug: FuturesContractFamilySlug);
     /**
      * 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).
      */
     latest(): Promise<FuturesPrice>;
     /**
@@ -307,16 +377,13 @@ export declare class 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}`);
  * });
@@ -326,18 +393,28 @@ export declare class FuturesResource {
     private client;
     constructor(client: OilPriceAPI);
     /**
-     * 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');
      * ```
      */
     latest(contract: string): Promise<FuturesPrice>;

package/dist/resources/futures.js

@@ -45,15 +45,34 @@ export const FUTURES_CONTRACTS = {
  * path segment used by the typed family helpers.
  */
 export const FUTURES_FAMILY_SLUGS = {
-    [FUTURES_CONTRACTS.BRENT]: "ice-brent",
-    [FUTURES_CONTRACTS.WTI]: "ice-wti",
-    [FUTURES_CONTRACTS.GASOIL]: "ice-gasoil",
-    [FUTURES_CONTRACTS.NATURAL_GAS]: "natural-gas",
-    [FUTURES_CONTRACTS.TTF_GAS]: "ttf-gas",
-    [FUTURES_CONTRACTS.LNG_JKM]: "lng-jkm",
-    [FUTURES_CONTRACTS.EUA_CARBON]: "eua-carbon",
-    [FUTURES_CONTRACTS.UK_CARBON]: "uk-carbon",
+    [FUTURES_CONTRACTS.BRENT]: "ice-brent", // BZ
+    [FUTURES_CONTRACTS.WTI]: "ice-wti", // CL
+    [FUTURES_CONTRACTS.GASOIL]: "ice-gasoil", // G
+    QS: "ice-gasoil", // ICE Gasoil also trades under the QS ticker prefix
+    [FUTURES_CONTRACTS.NATURAL_GAS]: "natural-gas", // NG
+    [FUTURES_CONTRACTS.TTF_GAS]: "ttf-gas", // TTF
+    [FUTURES_CONTRACTS.LNG_JKM]: "lng-jkm", // JKM
+    [FUTURES_CONTRACTS.EUA_CARBON]: "eua-carbon", // EUA
+    [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.
+ */
+export function resolveFuturesFamilySlug(codeOrSlug) {
+    const trimmed = codeOrSlug.trim();
+    // Direct code match (case-insensitive — codes are upper-case).
+    const byCode = FUTURES_FAMILY_SLUGS[trimmed.toUpperCase()];
+    if (byCode)
+        return byCode;
+    // Already a valid family slug?
+    const lower = trimmed.toLowerCase();
+    const isSlug = Object.values(FUTURES_FAMILY_SLUGS).includes(lower);
+    return isSlug ? lower : null;
+}
 /**
  * Typed helper for a single futures contract family (e.g., ICE Brent, Gasoil).
  *
@@ -77,9 +96,12 @@ export 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.
@@ -152,16 +174,13 @@ export class 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}`);
  * });
@@ -172,25 +191,42 @@ export 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 ValidationError("Contract symbol must be a non-empty string");
         }
-        return this.client["request"](`/v1/futures/${contract}`, {});
+        const slug = resolveFuturesFamilySlug(contract);
+        if (!slug) {
+            throw new 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/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") {