oilpriceapi 0.8.2 → 0.9.0

package/dist/client.js

@@ -14,6 +14,10 @@ import { EnergyIntelligenceResource } from "./resources/ei/index.js";
 import { WebhooksResource } from "./resources/webhooks.js";
 import { DataSourcesResource } from "./resources/data-sources.js";
 import { SDK_VERSION, SDK_NAME, buildUserAgent } from "./version.js";
+import { SpreadsResource } from "./resources/spreads.js";
+import { IndicatorsResource } from "./resources/indicators.js";
+import { RawResource } from "./resources/raw.js";
+import { StreamingResource } from "./resources/streaming.js";
 /**
  * Official Node.js client for Oil Price API
  *
@@ -69,6 +73,10 @@ export class OilPriceAPI {
         this.ei = new EnergyIntelligenceResource(this);
         this.webhooks = new WebhooksResource(this);
         this.dataSources = new DataSourcesResource(this);
+        this.spreads = new SpreadsResource(this);
+        this.indicators = new IndicatorsResource(this);
+        this.raw = new RawResource(this);
+        this.stream = new StreamingResource(this);
     }
     /**
      * Log debug messages if debug mode is enabled
@@ -122,12 +130,51 @@ export class OilPriceAPI {
         // Don't retry on client errors (4xx except 429)
         return false;
     }
+    /**
+     * Shape a parsed JSON response body into the value returned to callers.
+     *
+     * Centralizes the response-structure handling so that both {@link request}
+     * and {@link requestRaw} return identical data. Handles the latest/historical
+     * envelope shapes as well as the generic `{ data }` fallback used by resource
+     * mutations, alerts, webhooks, etc.
+     */
+    shapeResponseData(responseData) {
+        // Handle different response structures
+        // Latest endpoint: { status, data: { price, ... } }
+        // Historical endpoint: { status, data: { prices: [...] } }
+        if (responseData.status === "success" && responseData.data) {
+            if (responseData.data.prices) {
+                // Historical endpoint - return prices array
+                this.log(`Returning ${responseData.data.prices.length} prices`);
+                return responseData.data.prices;
+            }
+            else if (responseData.data.price !== undefined) {
+                // Latest endpoint - wrap single price in array
+                this.log("Returning single price (wrapped in array)");
+                return [responseData.data];
+            }
+        }
+        // Fallback - return data as-is (used by resource mutations, alerts, webhooks, etc.)
+        this.log("Returning data as-is");
+        return (responseData.data !== undefined ? responseData.data : responseData);
+    }
     /**
      * Internal method to make HTTP requests with retry and timeout.
      * Supports all HTTP methods (GET, POST, PATCH, DELETE) with consistent
      * retry logic, timeout handling, and typed error responses.
      */
     async request(endpoint, params, options) {
+        const { data } = await this.requestRaw(endpoint, params, options);
+        return data;
+    }
+    /**
+     * Internal method identical to {@link request} but returns the underlying
+     * HTTP status and headers alongside the parsed data.
+     *
+     * Used by the public {@link raw} accessor to expose response metadata
+     * (issue #7) without changing the return shape of existing methods.
+     */
+    async requestRaw(endpoint, params, options) {
         // Build URL with query parameters
         const url = new URL(`${this.baseUrl}${endpoint}`);
         if (params) {
@@ -218,7 +265,11 @@ export class OilPriceAPI {
                     const responseText = await response.text();
                     if (!responseText) {
                         this.log("Empty response body");
-                        return {};
+                        return {
+                            data: {},
+                            status: response.status,
+                            headers: response.headers,
+                        };
                     }
                     // Parse successful response
                     const responseData = JSON.parse(responseText);
@@ -226,24 +277,11 @@ export class OilPriceAPI {
                         status: responseData.status,
                         hasData: !!responseData.data,
                     });
-                    // Handle different response structures
-                    // Latest endpoint: { status, data: { price, ... } }
-                    // Historical endpoint: { status, data: { prices: [...] } }
-                    if (responseData.status === "success" && responseData.data) {
-                        if (responseData.data.prices) {
-                            // Historical endpoint - return prices array
-                            this.log(`Returning ${responseData.data.prices.length} prices`);
-                            return responseData.data.prices;
-                        }
-                        else if (responseData.data.price !== undefined) {
-                            // Latest endpoint - wrap single price in array
-                            this.log("Returning single price (wrapped in array)");
-                            return [responseData.data];
-                        }
-                    }
-                    // Fallback - return data as-is (used by resource mutations, alerts, webhooks, etc.)
-                    this.log("Returning data as-is");
-                    return (responseData.data !== undefined ? responseData.data : responseData);
+                    return {
+                        data: this.shapeResponseData(responseData),
+                        status: response.status,
+                        headers: response.headers,
+                    };
                 }
                 catch (error) {
                     // Handle abort (timeout)
@@ -483,4 +521,86 @@ export class OilPriceAPI {
     async getCommodity(code) {
         return this.request(`/v1/commodities/${code}`, {});
     }
+    /**
+     * Fetch live sample prices from the public, no-auth demo endpoint.
+     *
+     * Hits `GET /v1/demo/prices` (no API key required) and returns the parsed
+     * `{ prices, meta }` envelope. Useful for trying the client without
+     * credentials. Subject to the demo rate limit (~20 requests/hour).
+     *
+     * @example
+     * ```typescript
+     * const demo = await client.getDemoPrices();
+     * const brent = demo.prices.find(p => p.code === 'BRENT_CRUDE_USD');
+     * console.log(brent?.price);
+     * ```
+     */
+    async getDemoPrices() {
+        return this.requestDemo("/v1/demo/prices");
+    }
+    /**
+     * Fetch the catalogue of commodities from the public, no-auth demo endpoint.
+     *
+     * Hits `GET /v1/demo/commodities` (no API key required) and returns the parsed
+     * `{ commodities, meta }` envelope, where `meta.free_commodities` lists the
+     * codes available on the free demo tier.
+     *
+     * @example
+     * ```typescript
+     * const demo = await client.getDemoCommodities();
+     * console.log(demo.meta.total, demo.meta.free_commodities);
+     * ```
+     */
+    async getDemoCommodities() {
+        return this.requestDemo("/v1/demo/commodities");
+    }
+    /**
+     * Minimal fetch for the no-auth demo endpoints.
+     *
+     * Unlike {@link request}, this does NOT run the latest/historical response
+     * shaping (which would strip the `meta` block) and does NOT require an API
+     * key — it returns the raw `data` envelope from `{ status, data }`.
+     */
+    async requestDemo(endpoint) {
+        const url = `${this.baseUrl}${endpoint}`;
+        this.log(`Demo request: ${url}`);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(url, {
+                method: "GET",
+                headers: {
+                    "Content-Type": "application/json",
+                    "User-Agent": buildUserAgent(),
+                    "X-SDK-Name": SDK_NAME,
+                    "X-SDK-Version": SDK_VERSION,
+                },
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const body = await response.text();
+                let message = `HTTP ${response.status}: ${response.statusText}`;
+                try {
+                    const json = JSON.parse(body);
+                    message = json.message || json.error || message;
+                }
+                catch {
+                    // non-JSON error body
+                }
+                throw new OilPriceAPIError(message, response.status, "HTTP_ERROR");
+            }
+            const parsed = JSON.parse(await response.text());
+            // Demo envelope is { status: "success", data: { ... } }.
+            return (parsed.data !== undefined ? parsed.data : parsed);
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new TimeoutError("Request timeout", this.timeout);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
 }

package/dist/index.d.ts

@@ -6,15 +6,22 @@
  * @packageDocumentation
  */
 export { OilPriceAPI } from "./client.js";
+export type { APIResponse } from "./client.js";
 export { SDK_VERSION, SDK_NAME } from "./version.js";
-export type { OilPriceAPIConfig, RetryStrategy, Price, LatestPricesOptions, HistoricalPricesOptions, HistoricalPeriod, AggregationInterval, Commodity, CommoditiesResponse, CommodityCategory, CategoriesResponse, DataConnectorPrice, DataConnectorOptions, } from "./types.js";
+export type { OilPriceAPIConfig, RetryStrategy, Price, LatestPricesOptions, HistoricalPricesOptions, HistoricalPeriod, AggregationInterval, Commodity, CommoditiesResponse, CommodityCategory, CategoriesResponse, DataConnectorPrice, DataConnectorOptions, DemoPrice, DemoPricesResponse, DemoCommoditiesResponse, } from "./types.js";
 export type { DieselPrice, DieselStation, DieselStationsResponse, GetDieselStationsOptions, } from "./resources/diesel.js";
 export type { PriceAlert, CreateAlertParams, UpdateAlertParams, AlertOperator, } from "./resources/alerts.js";
-export type { FuturesPrice, HistoricalFuturesPrice, HistoricalFuturesOptions, FuturesOHLC, IntradayPrice, IntradayFuturesData, FuturesSpread, FuturesCurvePoint, FuturesCurveData, ContinuousContractPrice, ContinuousFuturesData, } from "./resources/futures.js";
+export type { FuturesPrice, HistoricalFuturesPrice, HistoricalFuturesOptions, FuturesOHLC, IntradayPrice, IntradayFuturesData, FuturesSpread, FuturesCurvePoint, FuturesCurveData, ContinuousContractPrice, ContinuousFuturesData, FuturesSpreadHistoryPoint, FuturesSpreadHistory, FuturesContractFamilySlug, } from "./resources/futures.js";
+export { FUTURES_CONTRACTS, FUTURES_FAMILY_SLUGS, FuturesContractFamily, } from "./resources/futures.js";
+export type { SpreadType, SpreadValue, HistoricalSpreadValue, HistoricalSpreadOptions, } from "./resources/spreads.js";
+export { SpreadsResource } from "./resources/spreads.js";
+export type { IndicatorType, FuelSwitchingIndicator, PriceContextIndicator, StorageAnalyticsIndicator, AnnotationIndicator, CFTCPositioningIndicator, CongressionalTradeIndicator, } from "./resources/indicators.js";
+export { IndicatorsResource } from "./resources/indicators.js";
+export { RawResource } from "./resources/raw.js";
 export type { StorageData, HistoricalStorageData, HistoricalStorageOptions, } from "./resources/storage.js";
 export type { RigCountData, HistoricalRigCountData, HistoricalRigCountOptions, RigCountTrend, RigCountSummary, } from "./resources/rig-counts.js";
 export type { BunkerFuelPrice, PortBunkerPrices, PortPriceComparison, BunkerFuelSpreads, HistoricalBunkerPrice, HistoricalBunkerOptions, } from "./resources/bunker-fuels.js";
-export type { PerformanceMetrics, PerformanceOptions, StatisticalAnalysis, CorrelationAnalysis, TrendAnalysis, SpreadAnalysis, ForecastPoint, PriceForecast as AnalyticsPriceForecast, } from "./resources/analytics.js";
+export type { PerformanceMetrics, PerformanceOptions, StatisticalAnalysis, CorrelationAnalysis, CorrelationOptions, TrendAnalysis, TrendOptions, SpreadAnalysis, SpreadOptions, ForecastOptions, PriceForecast as AnalyticsPriceForecast, } from "./resources/analytics.js";
 export type { MonthlyForecast, ForecastAccuracy, ArchivedForecast } from "./resources/forecasts.js";
 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";
@@ -36,6 +43,8 @@ export { DrillingIntelligenceResource } from "./resources/drilling.js";
 export { EnergyIntelligenceResource, EIRigCountsResource, EIOilInventoriesResource, EIOPECProductionResource, EIDrillingProductivityResource, EIForecastsResource, EIWellPermitsResource, EIFracFocusResource, } from "./resources/ei/index.js";
 export { WebhooksResource } from "./resources/webhooks.js";
 export { DataSourcesResource } from "./resources/data-sources.js";
+export { StreamingResource, PriceStreamSubscription, ENERGY_PRICES_CHANNEL, } from "./resources/streaming.js";
+export type { StreamPricesOptions, PriceUpdateHandler, StreamMessage, WelcomeMessage, PriceUpdateMessage, RigCountUpdateMessage, StreamedPrice, StreamedPriceMap, } from "./resources/streaming.js";
 /**
  * Standalone webhook signature verification.
  *

package/dist/index.js

@@ -8,6 +8,10 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 export { OilPriceAPI } from "./client.js";
 export { SDK_VERSION, SDK_NAME } from "./version.js";
+export { FUTURES_CONTRACTS, FUTURES_FAMILY_SLUGS, FuturesContractFamily, } from "./resources/futures.js";
+export { SpreadsResource } from "./resources/spreads.js";
+export { IndicatorsResource } from "./resources/indicators.js";
+export { RawResource } from "./resources/raw.js";
 export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, ValidationError, TimeoutError, } from "./errors.js";
 export { DieselResource } from "./resources/diesel.js";
 export { AlertsResource } from "./resources/alerts.js";
@@ -23,6 +27,7 @@ export { DrillingIntelligenceResource } from "./resources/drilling.js";
 export { EnergyIntelligenceResource, EIRigCountsResource, EIOilInventoriesResource, EIOPECProductionResource, EIDrillingProductivityResource, EIForecastsResource, EIWellPermitsResource, EIFracFocusResource, } from "./resources/ei/index.js";
 export { WebhooksResource } from "./resources/webhooks.js";
 export { DataSourcesResource } from "./resources/data-sources.js";
+export { StreamingResource, PriceStreamSubscription, ENERGY_PRICES_CHANNEL, } from "./resources/streaming.js";
 /**
  * Standalone webhook signature verification.
  *