oilpriceapi 0.8.2 → 0.9.1

package/dist/cjs/resources/analytics.js

@@ -4,6 +4,13 @@
  *
  * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnalyticsResource = void 0;
@@ -20,13 +27,8 @@ const errors_js_1 = require("../errors.js");
  *
  * 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}`);
  * ```
  */
@@ -35,192 +37,152 @@ 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") {
+    async statistics(code, period) {
+        if (!code || typeof code !== "string") {
             throw new errors_js_1.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") {
+    async correlation(code1, code2, options) {
+        if (!code1 || typeof code1 !== "string") {
             throw new errors_js_1.ValidationError("First commodity code must be a non-empty string");
         }
-        if (!commodity2 || typeof commodity2 !== "string") {
+        if (!code2 || typeof code2 !== "string") {
             throw new errors_js_1.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") {
+    async trend(code, options) {
+        if (!code || typeof code !== "string") {
             throw new errors_js_1.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
+     * Analyze a named commodity spread (basis / crack / ratio).
      *
-     * Calculates current spread and compares to historical patterns.
+     * 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.
      *
-     * @param commodity1 - First commodity code
-     * @param commodity2 - Second commodity code
-     * @returns Spread analysis
-     *
-     * @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 errors_js_1.ValidationError("First commodity code must be a non-empty string");
-        }
-        if (!commodity2 || typeof commodity2 !== "string") {
-            throw new errors_js_1.ValidationError("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 errors_js_1.ValidationError("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);
     }
 }
 exports.AnalyticsResource = AnalyticsResource;

package/dist/cjs/resources/bunker-fuels.js

@@ -54,7 +54,8 @@ 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;
     }
     /**
@@ -107,24 +108,33 @@ class BunkerFuelsResource {
         });
     }
     /**
-     * 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 errors_js_1.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
@@ -137,9 +147,16 @@ 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'
      * });
@@ -149,22 +166,19 @@ class BunkerFuelsResource {
      * });
      * ```
      */
-    async historical(port, fuelType, options) {
+    async historical(port, options) {
         if (!port || typeof port !== "string") {
             throw new errors_js_1.ValidationError("Port code must be a non-empty string");
         }
-        if (!fuelType || typeof fuelType !== "string") {
-            throw new errors_js_1.ValidationError("Fuel type 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/cjs/resources/data-sources.js

@@ -123,22 +123,18 @@ class DataSourcesResource {
         if (!params.name || typeof params.name !== "string") {
             throw new errors_js_1.ValidationError("Data source name is required");
         }
-        if (!params.type) {
-            throw new errors_js_1.ValidationError("Data source type is required");
-        }
-        if (!params.config || typeof params.config !== "object") {
-            throw new errors_js_1.ValidationError("Data source config is required");
+        if (!params.source_type) {
+            throw new errors_js_1.ValidationError("Data source source_type is required");
         }
         const response = await this.client["request"]("/v1/data-sources", {}, {
             method: "POST",
             body: {
                 data_source: {
                     name: params.name,
-                    type: params.type,
-                    config: params.config,
-                    enabled: params.enabled ?? true,
-                    sync_frequency_minutes: params.sync_frequency_minutes ?? 60,
-                    metadata: params.metadata,
+                    source_type: params.source_type,
+                    status: params.status,
+                    credentials: params.credentials,
+                    scraper_config: params.scraper_config,
                 },
             },
         });
@@ -287,11 +283,16 @@ class DataSourcesResource {
      * console.log(`Credential rotation: ${result.success ? 'success' : 'failed'}`);
      * ```
      */
-    async rotateCredentials(id) {
+    async rotateCredentials(id, credentials) {
         if (!id || typeof id !== "string") {
             throw new errors_js_1.ValidationError("Data source ID must be a non-empty string");
         }
-        return this.client["request"](`/v1/data-sources/${id}/rotate-credentials`, {}, { method: "POST" });
+        if (!credentials || typeof credentials !== "object") {
+            throw new errors_js_1.ValidationError("New credentials object is required");
+        }
+        // Route is POST /v1/data-sources/:id/rotate_credentials (underscore) and
+        // the controller does params.require(:credentials).
+        return this.client["request"](`/v1/data-sources/${id}/rotate_credentials`, {}, { method: "POST", body: { credentials } });
     }
 }
 exports.DataSourcesResource = DataSourcesResource;

package/dist/cjs/resources/ei/frac-focus.js

@@ -112,12 +112,22 @@ class EIFracFocusResource {
      */
     async search(query) {
         const params = {};
-        if (query.state)
-            params.state = query.state;
-        if (query.operator)
-            params.operator = query.operator;
-        if (query.chemical)
-            params.chemical = query.chemical;
+        if (query.states)
+            params.states = query.states;
+        if (query.county)
+            params.county = query.county;
+        if (query.well_name)
+            params.well_name = query.well_name;
+        if (query.api_number)
+            params.api_number = query.api_number;
+        if (query.min_water_gallons !== undefined)
+            params.min_water_gallons = query.min_water_gallons.toString();
+        if (query.latitude !== undefined)
+            params.latitude = query.latitude.toString();
+        if (query.longitude !== undefined)
+            params.longitude = query.longitude.toString();
+        if (query.radius_miles !== undefined)
+            params.radius_miles = query.radius_miles.toString();
         if (query.start_date)
             params.start_date = query.start_date;
         if (query.end_date)

package/dist/cjs/resources/ei/well-permits.js

@@ -107,12 +107,24 @@ class EIWellPermitsResource {
      */
     async search(query) {
         const params = {};
-        if (query.state)
-            params.state = query.state;
-        if (query.operator)
-            params.operator = query.operator;
-        if (query.formation)
-            params.formation = query.formation;
+        if (query.states)
+            params.states = query.states;
+        if (query.county)
+            params.county = query.county;
+        if (query.well_name)
+            params.well_name = query.well_name;
+        if (query.permit_type)
+            params.permit_type = query.permit_type;
+        if (query.well_type)
+            params.well_type = query.well_type;
+        if (query.address)
+            params.address = query.address;
+        if (query.latitude !== undefined)
+            params.latitude = query.latitude.toString();
+        if (query.longitude !== undefined)
+            params.longitude = query.longitude.toString();
+        if (query.radius_miles !== undefined)
+            params.radius_miles = query.radius_miles.toString();
         if (query.start_date)
             params.start_date = query.start_date;
         if (query.end_date)

package/dist/cjs/resources/forecasts.js

@@ -88,7 +88,8 @@ class ForecastsResource {
      * ```
      */
     async accuracy() {
-        return this.client["request"]("/v1/forecasts/accuracy", {});
+        // Route is /v1/forecasts/monthly/accuracy (the bare /accuracy 404s).
+        return this.client["request"]("/v1/forecasts/monthly/accuracy", {});
     }
     /**
      * Get archived forecasts
@@ -119,11 +120,16 @@ class ForecastsResource {
      * });
      * ```
      */
-    async archive(year) {
+    async archive(options) {
+        // Route is /v1/forecasts/monthly/archive (the bare /archive 404s). The
+        // controller reads only `page` / `per_page` — it does NOT filter by year,
+        // so the previous `year` argument was silently ignored.
         const params = {};
-        if (year)
-            params.year = year.toString();
-        const response = await this.client["request"]("/v1/forecasts/archive", params);
+        if (options?.page !== undefined)
+            params.page = options.page.toString();
+        if (options?.perPage !== undefined)
+            params.per_page = options.perPage.toString();
+        const response = await this.client["request"]("/v1/forecasts/monthly/archive", params);
         return Array.isArray(response) ? response : response.forecasts;
     }
     /**