oilpriceapi 0.7.0 → 0.9.0

package/dist/resources/analytics.js

@@ -3,7 +3,15 @@
  *
  * Access advanced analytics including performance metrics, statistical analysis,
  * correlations, trend detection, spreads, and forecasts.
+ *
+ * NOTE ON PARAMETERS: The OilPriceAPI analytics controller reads commodity
+ * identifiers as `code` / `code1` / `code2` and the lookback window as `period`
+ * (in days). Earlier versions of this SDK sent `commodity` / `commodity1` /
+ * `commodity2` / `days`, which the API silently ignored (and `correlation`
+ * returned "code1 and code2 parameters are required"). These methods now send
+ * the parameter names the controller actually reads.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Analytics Resource
  *
@@ -16,13 +24,8 @@
  *
  * const client = new OilPriceAPI({ apiKey: 'your_key' });
  *
- * // Get performance metrics
- * const perf = await client.analytics.performance({ commodity: 'WTI_USD', days: 30 });
- * console.log(`30-day return: ${perf.return_percent}%`);
- * console.log(`Volatility: ${perf.volatility}`);
- *
- * // Analyze correlation
- * const corr = await client.analytics.correlation('WTI_USD', 'BRENT_CRUDE_USD', 90);
+ * // Analyze correlation between two commodities (90-day window)
+ * const corr = await client.analytics.correlation('WTI_USD', 'BRENT_CRUDE_USD', { period: 90 });
  * console.log(`Correlation: ${corr.correlation}`);
  * ```
  */
@@ -31,191 +34,151 @@ export class AnalyticsResource {
         this.client = client;
     }
     /**
-     * Get performance metrics for a commodity
-     *
-     * Returns key performance indicators including returns, volatility,
-     * and price range over a specified period.
-     *
-     * @param options - Analysis parameters
-     * @returns Performance metrics
+     * Get the authenticated user's API usage analytics for the dashboard.
      *
-     * @throws {OilPriceAPIError} If API request fails
+     * Maps to `GET /v1/analytics/performance`, which reads a `range`
+     * parameter (`7d` | `30d` | `90d`).
      *
-     * @example
-     * ```typescript
-     * const metrics = await client.analytics.performance({
-     *   commodity: 'WTI_USD',
-     *   days: 30
-     * });
-     * console.log(`Return: ${metrics.return_percent}%`);
-     * console.log(`Volatility: ${metrics.volatility}`);
-     * console.log(`High: $${metrics.high}, Low: $${metrics.low}`);
-     * ```
+     * @param options - `{ range }` (default range '30d')
+     * @returns Usage analytics (overview, daily usage, endpoint breakdown, ...)
      */
     async performance(options) {
         const params = {};
-        if (options?.commodity)
-            params.commodity = options.commodity;
-        if (options?.days)
-            params.days = options.days.toString();
+        if (options?.range)
+            params.range = options.range;
         return this.client["request"]("/v1/analytics/performance", params);
     }
     /**
-     * Get statistical analysis for a commodity
+     * Get statistical analysis for a commodity.
      *
-     * Returns comprehensive statistical metrics including mean, median,
-     * standard deviation, and distribution characteristics.
+     * Maps to `GET /v1/analytics/statistics`, which reads `code` and `period`.
      *
-     * @param commodity - Commodity code to analyze
-     * @param days - Number of days to analyze (default: 30)
+     * @param code - Commodity code to analyze (e.g. 'WTI_USD')
+     * @param period - Lookback window in days (default: 30)
      * @returns Statistical analysis
      *
-     * @throws {NotFoundError} If commodity not found
-     * @throws {OilPriceAPIError} If API request fails
-     *
-     * @example
-     * ```typescript
-     * const stats = await client.analytics.statistics('BRENT_CRUDE_USD', 90);
-     * console.log(`Mean: $${stats.mean}`);
-     * console.log(`Std Dev: ${stats.std_dev}`);
-     * console.log(`Range: $${stats.min} - $${stats.max}`);
-     * ```
+     * @throws {ValidationError} If code is empty
      */
-    async statistics(commodity, days) {
-        if (!commodity || typeof commodity !== "string") {
-            throw new Error("Commodity code must be a non-empty string");
+    async statistics(code, period) {
+        if (!code || typeof code !== "string") {
+            throw new ValidationError("Commodity code must be a non-empty string");
         }
-        const params = { commodity };
-        if (days)
-            params.days = days.toString();
+        const params = { code };
+        if (period !== undefined)
+            params.period = period.toString();
         return this.client["request"]("/v1/analytics/statistics", params);
     }
     /**
-     * Analyze correlation between two commodities
+     * Analyze correlation between two commodities.
      *
-     * Calculates the Pearson correlation coefficient to measure how closely
-     * two commodities move together.
+     * Maps to `GET /v1/analytics/correlation`, which reads `code1`, `code2`,
+     * `period` and optional `type`, `window`, `codes`.
      *
-     * @param commodity1 - First commodity code
-     * @param commodity2 - Second commodity code
-     * @param days - Number of days to analyze (default: 30)
+     * @param code1 - First commodity code
+     * @param code2 - Second commodity code
+     * @param options - Lookback window in days, or `{ period, type, window, codes }`
      * @returns Correlation analysis
      *
-     * @throws {NotFoundError} If either commodity not found
-     * @throws {OilPriceAPIError} If API request fails
+     * @throws {ValidationError} If either code is empty
      *
      * @example
      * ```typescript
-     * const corr = await client.analytics.correlation('WTI_USD', 'BRENT_CRUDE_USD', 90);
-     * console.log(`Correlation: ${corr.correlation}`);
-     * console.log(`Strength: ${corr.strength}`);
-     * console.log(`R-squared: ${corr.r_squared}`);
+     * const corr = await client.analytics.correlation('WTI_USD', 'BRENT_CRUDE_USD', { period: 90 });
+     * console.log(corr.correlation);
      * ```
      */
-    async correlation(commodity1, commodity2, days) {
-        if (!commodity1 || typeof commodity1 !== "string") {
-            throw new Error("First commodity code must be a non-empty string");
+    async correlation(code1, code2, options) {
+        if (!code1 || typeof code1 !== "string") {
+            throw new ValidationError("First commodity code must be a non-empty string");
         }
-        if (!commodity2 || typeof commodity2 !== "string") {
-            throw new Error("Second commodity code must be a non-empty string");
+        if (!code2 || typeof code2 !== "string") {
+            throw new ValidationError("Second commodity code must be a non-empty string");
         }
-        const params = {
-            commodity1,
-            commodity2,
-        };
-        if (days)
-            params.days = days.toString();
+        const opts = typeof options === "number" ? { period: options } : options || {};
+        const params = { code1, code2 };
+        if (opts.period !== undefined)
+            params.period = opts.period.toString();
+        if (opts.type)
+            params.type = opts.type;
+        if (opts.window !== undefined)
+            params.window = opts.window.toString();
+        if (opts.codes && opts.codes.length > 0)
+            params.codes = opts.codes.join(",");
         return this.client["request"]("/v1/analytics/correlation", params);
     }
     /**
-     * Analyze price trend for a commodity
+     * Analyze price trend for a commodity.
      *
-     * Detects trend direction, strength, and key levels (support/resistance).
+     * Maps to `GET /v1/analytics/trend`, which reads `code`, `period` and
+     * optional `type` ('analysis' | 'sma' | 'ema' | 'rsi' | 'levels') and `window`.
      *
-     * @param commodity - Commodity code to analyze
-     * @param days - Number of days to analyze (default: 30)
+     * @param code - Commodity code to analyze
+     * @param options - Lookback window in days, or `{ period, type, window }`
      * @returns Trend analysis
      *
-     * @throws {NotFoundError} If commodity not found
-     * @throws {OilPriceAPIError} If API request fails
-     *
-     * @example
-     * ```typescript
-     * const trend = await client.analytics.trend('WTI_USD', 60);
-     * console.log(`Trend: ${trend.trend} (strength: ${trend.strength})`);
-     * console.log(`Support: $${trend.support}`);
-     * console.log(`Resistance: $${trend.resistance}`);
-     * ```
+     * @throws {ValidationError} If code is empty
      */
-    async trend(commodity, days) {
-        if (!commodity || typeof commodity !== "string") {
-            throw new Error("Commodity code must be a non-empty string");
+    async trend(code, options) {
+        if (!code || typeof code !== "string") {
+            throw new ValidationError("Commodity code must be a non-empty string");
         }
-        const params = { commodity };
-        if (days)
-            params.days = days.toString();
+        const opts = typeof options === "number" ? { period: options } : options || {};
+        const params = { code };
+        if (opts.period !== undefined)
+            params.period = opts.period.toString();
+        if (opts.type)
+            params.type = opts.type;
+        if (opts.window !== undefined)
+            params.window = opts.window.toString();
         return this.client["request"]("/v1/analytics/trend", params);
     }
     /**
-     * Analyze spread between two commodities
-     *
-     * Calculates current spread and compares to historical patterns.
+     * Analyze a named commodity spread (basis / crack / ratio).
      *
-     * @param commodity1 - First commodity code
-     * @param commodity2 - Second commodity code
-     * @returns Spread analysis
+     * Maps to `GET /v1/analytics/spread`, which reads `spread` (the named spread,
+     * e.g. 'wti_brent'), `period` and optional `type` ('current' | 'historical').
+     * Call with no `spread` to list the available named spreads.
      *
-     * @throws {NotFoundError} If either commodity not found
-     * @throws {OilPriceAPIError} If API request fails
+     * @param spread - Named spread (e.g. 'wti_brent'); omit to list available spreads
+     * @param options - Lookback window in days, or `{ period, type }`
+     * @returns Spread analysis (or the list of available spreads)
      *
      * @example
      * ```typescript
-     * const spread = await client.analytics.spread('BRENT_CRUDE_USD', 'WTI_USD');
-     * console.log(`Current spread: $${spread.spread}`);
-     * console.log(`Average spread: $${spread.average_spread}`);
-     * console.log(`Z-score: ${spread.z_score}`);
+     * const spread = await client.analytics.spread('wti_brent', { period: 30 });
+     * console.log(spread.current_spread);
      * ```
      */
-    async spread(commodity1, commodity2) {
-        if (!commodity1 || typeof commodity1 !== "string") {
-            throw new Error("First commodity code must be a non-empty string");
-        }
-        if (!commodity2 || typeof commodity2 !== "string") {
-            throw new Error("Second commodity code must be a non-empty string");
-        }
-        return this.client["request"]("/v1/analytics/spread", {
-            commodity1,
-            commodity2,
-        });
+    async spread(spread, options) {
+        const opts = typeof options === "number" ? { period: options } : options || {};
+        const params = {};
+        if (spread)
+            params.spread = spread;
+        if (opts.period !== undefined)
+            params.period = opts.period.toString();
+        if (opts.type)
+            params.type = opts.type;
+        return this.client["request"]("/v1/analytics/spread", params);
     }
     /**
-     * Get price forecast for a commodity
-     *
-     * Returns forecasted prices with confidence intervals.
-     *
-     * @param commodity - Commodity code to forecast
-     * @returns Price forecast
+     * Get a statistical price forecast for a commodity.
      *
-     * @throws {NotFoundError} If commodity not found
-     * @throws {OilPriceAPIError} If API request fails
+     * Maps to `GET /v1/analytics/forecast`, which reads `code`, `method`
+     * (default 'ema') and `period` (default 90). Call with no `code` to list
+     * the available forecast methods.
      *
-     * @example
-     * ```typescript
-     * const forecast = await client.analytics.forecast('WTI_USD');
-     * console.log(`Forecast model: ${forecast.model}`);
-     * console.log(`Horizon: ${forecast.horizon_days} days`);
-     *
-     * forecast.forecast.forEach(point => {
-     *   console.log(`${point.date}: $${point.price} (${point.lower_bound}-${point.upper_bound})`);
-     * });
-     * ```
+     * @param code - Commodity code to forecast; omit to list available methods
+     * @param options - `{ method, period }`
+     * @returns Price forecast (or the list of available methods)
      */
-    async forecast(commodity) {
-        if (!commodity || typeof commodity !== "string") {
-            throw new Error("Commodity code must be a non-empty string");
-        }
-        return this.client["request"]("/v1/analytics/forecast", {
-            commodity,
-        });
+    async forecast(code, options) {
+        const params = {};
+        if (code)
+            params.code = code;
+        if (options?.method)
+            params.method = options.method;
+        if (options?.period !== undefined)
+            params.period = options.period.toString();
+        return this.client["request"]("/v1/analytics/forecast", params);
     }
 }

package/dist/resources/bunker-fuels.d.ts

@@ -115,13 +115,29 @@ export interface HistoricalBunkerPrice {
     unit: string;
 }
 /**
- * Options for historical bunker fuel query
+ * Options for historical bunker fuel query.
+ *
+ * The controller reads `from` / `to` (dates) and `interval` — not `start_date` /
+ * `end_date` / `fuel_type`. History is returned per port (all grades).
  */
 export interface HistoricalBunkerOptions {
     /** Start date in ISO 8601 format (YYYY-MM-DD) */
     startDate?: string;
     /** End date in ISO 8601 format (YYYY-MM-DD) */
     endDate?: string;
+    /** Aggregation interval (e.g. 'daily') */
+    interval?: string;
+}
+/**
+ * Options for port-to-port bunker spread query.
+ */
+export interface BunkerSpreadOptions {
+    /** Origin port code */
+    from: string;
+    /** Destination port code */
+    to: string;
+    /** Fuel grade (e.g. 'VLSFO') */
+    grade?: string;
 }
 /**
  * Bunker Fuels Resource
@@ -206,23 +222,23 @@ export declare class BunkerFuelsResource {
      */
     compare(ports: string[]): Promise<PortPriceComparison>;
     /**
-     * Get bunker fuel price spreads
+     * Get the bunker fuel price spread between two ports.
      *
-     * Returns spreads between different fuel grades (e.g., VLSFO-IFO380).
+     * Maps to `GET /v1/bunker-fuels/spreads/ports`, which reads `from`, `to`
+     * and `grade`. (Earlier SDKs called `/v1/bunker-fuels/spreads` with no params,
+     * which 404'd.)
      *
-     * @returns Fuel price spreads
+     * @param options - `{ from, to, grade? }`
+     * @returns Port-to-port fuel price spread
      *
-     * @throws {OilPriceAPIError} If API request fails
+     * @throws {ValidationError} If from/to are missing
      *
      * @example
      * ```typescript
-     * const spreads = await client.bunkerFuels.spreads();
-     * spreads.spreads.forEach(spread => {
-     *   console.log(`${spread.fuel1}-${spread.fuel2} spread: $${spread.average_spread}`);
-     * });
+     * const spread = await client.bunkerFuels.spreads({ from: 'SIN', to: 'RTM', grade: 'VLSFO' });
      * ```
      */
-    spreads(): Promise<BunkerFuelSpreads>;
+    spreads(options: BunkerSpreadOptions): Promise<BunkerFuelSpreads>;
     /**
      * Get historical bunker fuel prices
      *
@@ -234,9 +250,16 @@ export declare class BunkerFuelsResource {
      * @throws {NotFoundError} If port or fuel type not found
      * @throws {OilPriceAPIError} If API request fails
      *
+     * The history endpoint is keyed by port in the PATH (`/historical/:port_code`)
+     * and returns all grades for that port; it does not filter by a single fuel
+     * type. It reads `from` / `to` / `interval` query params.
+     *
+     * @param port - Port code (e.g., "SIN", "RTM") — used as a path segment
+     * @param options - `{ startDate, endDate, interval }`
+     *
      * @example
      * ```typescript
-     * const history = await client.bunkerFuels.historical('SIN', 'VLSFO', {
+     * const history = await client.bunkerFuels.historical('SIN', {
      *   startDate: '2024-01-01',
      *   endDate: '2024-12-31'
      * });
@@ -246,7 +269,7 @@ export declare class BunkerFuelsResource {
      * });
      * ```
      */
-    historical(port: string, fuelType: string, options?: HistoricalBunkerOptions): Promise<HistoricalBunkerPrice[]>;
+    historical(port: string, options?: HistoricalBunkerOptions): Promise<HistoricalBunkerPrice[]>;
     /**
      * Export bunker fuel data
      *

package/dist/resources/bunker-fuels.js

@@ -4,6 +4,7 @@
  * Access bunker fuel prices at major ports worldwide, including VLSFO, MGO,
  * and IFO380. Compare prices across ports and track historical trends.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Bunker Fuels Resource
  *
@@ -50,7 +51,8 @@ export class BunkerFuelsResource {
      * ```
      */
     async all() {
-        const response = await this.client["request"]("/v1/bunker-fuels", {});
+        // Route is GET /v1/bunker-fuels/all (the bare /v1/bunker-fuels has no route).
+        const response = await this.client["request"]("/v1/bunker-fuels/all", {});
         return Array.isArray(response) ? response : response.prices;
     }
     /**
@@ -72,7 +74,7 @@ export class BunkerFuelsResource {
      */
     async port(code) {
         if (!code || typeof code !== "string") {
-            throw new Error("Port code must be a non-empty string");
+            throw new ValidationError("Port code must be a non-empty string");
         }
         return this.client["request"](`/v1/bunker-fuels/ports/${code}`, {});
     }
@@ -96,31 +98,40 @@ export class BunkerFuelsResource {
      */
     async compare(ports) {
         if (!Array.isArray(ports) || ports.length === 0) {
-            throw new Error("Ports must be a non-empty array of port codes");
+            throw new ValidationError("Ports must be a non-empty array of port codes");
         }
         return this.client["request"]("/v1/bunker-fuels/compare", {
             ports: ports.join(","),
         });
     }
     /**
-     * Get bunker fuel price spreads
+     * Get the bunker fuel price spread between two ports.
      *
-     * Returns spreads between different fuel grades (e.g., VLSFO-IFO380).
+     * Maps to `GET /v1/bunker-fuels/spreads/ports`, which reads `from`, `to`
+     * and `grade`. (Earlier SDKs called `/v1/bunker-fuels/spreads` with no params,
+     * which 404'd.)
      *
-     * @returns Fuel price spreads
+     * @param options - `{ from, to, grade? }`
+     * @returns Port-to-port fuel price spread
      *
-     * @throws {OilPriceAPIError} If API request fails
+     * @throws {ValidationError} If from/to are missing
      *
      * @example
      * ```typescript
-     * const spreads = await client.bunkerFuels.spreads();
-     * spreads.spreads.forEach(spread => {
-     *   console.log(`${spread.fuel1}-${spread.fuel2} spread: $${spread.average_spread}`);
-     * });
+     * const spread = await client.bunkerFuels.spreads({ from: 'SIN', to: 'RTM', grade: 'VLSFO' });
      * ```
      */
-    async spreads() {
-        return this.client["request"]("/v1/bunker-fuels/spreads", {});
+    async spreads(options) {
+        if (!options?.from || !options?.to) {
+            throw new ValidationError("Both 'from' and 'to' port codes are required");
+        }
+        const params = {
+            from: options.from,
+            to: options.to,
+        };
+        if (options.grade)
+            params.grade = options.grade;
+        return this.client["request"]("/v1/bunker-fuels/spreads/ports", params);
     }
     /**
      * Get historical bunker fuel prices
@@ -133,9 +144,16 @@ export class BunkerFuelsResource {
      * @throws {NotFoundError} If port or fuel type not found
      * @throws {OilPriceAPIError} If API request fails
      *
+     * The history endpoint is keyed by port in the PATH (`/historical/:port_code`)
+     * and returns all grades for that port; it does not filter by a single fuel
+     * type. It reads `from` / `to` / `interval` query params.
+     *
+     * @param port - Port code (e.g., "SIN", "RTM") — used as a path segment
+     * @param options - `{ startDate, endDate, interval }`
+     *
      * @example
      * ```typescript
-     * const history = await client.bunkerFuels.historical('SIN', 'VLSFO', {
+     * const history = await client.bunkerFuels.historical('SIN', {
      *   startDate: '2024-01-01',
      *   endDate: '2024-12-31'
      * });
@@ -145,22 +163,19 @@ export class BunkerFuelsResource {
      * });
      * ```
      */
-    async historical(port, fuelType, options) {
+    async historical(port, options) {
         if (!port || typeof port !== "string") {
-            throw new Error("Port code must be a non-empty string");
-        }
-        if (!fuelType || typeof fuelType !== "string") {
-            throw new Error("Fuel type must be a non-empty string");
+            throw new ValidationError("Port code must be a non-empty string");
         }
-        const params = {
-            port,
-            fuel_type: fuelType,
-        };
+        const params = {};
         if (options?.startDate)
-            params.start_date = options.startDate;
+            params.from = options.startDate;
         if (options?.endDate)
-            params.end_date = options.endDate;
-        const response = await this.client["request"]("/v1/bunker-fuels/historical", params);
+            params.to = options.endDate;
+        if (options?.interval)
+            params.interval = options.interval;
+        // Port code is a PATH segment: GET /v1/bunker-fuels/historical/:port_code
+        const response = await this.client["request"](`/v1/bunker-fuels/historical/${port}`, params);
         return Array.isArray(response) ? response : response.data;
     }
     /**

package/dist/resources/commodities.js

@@ -3,6 +3,7 @@
  *
  * Get metadata about supported commodities and categories.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Commodities Resource
  *
@@ -75,7 +76,7 @@ export class CommoditiesResource {
      */
     async get(code) {
         if (!code || typeof code !== "string") {
-            throw new Error("Commodity code must be a non-empty string");
+            throw new ValidationError("Commodity code must be a non-empty string");
         }
         return this.client["request"](`/v1/commodities/${code}`, {});
     }

package/dist/resources/data-quality.js

@@ -3,6 +3,7 @@
  *
  * Access data quality metrics, reports, and monitoring for commodity price data.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Data Quality Resource
  *
@@ -132,7 +133,7 @@ export class DataQualityResource {
      */
     async report(code) {
         if (!code || typeof code !== "string") {
-            throw new Error("Report code must be a non-empty string");
+            throw new ValidationError("Report code must be a non-empty string");
         }
         return this.client["request"](`/v1/data-quality/reports/${code}`, {});
     }