oilpriceapi 0.7.0 → 0.8.2

package/dist/cjs/resources/analytics.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Analytics Resource
+ *
+ * Access advanced analytics including performance metrics, statistical analysis,
+ * correlations, trend detection, spreads, and forecasts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyticsResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Analytics Resource
+ *
+ * Access advanced analytics including performance metrics, statistical analysis,
+ * correlations, trends, spreads, and forecasts.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * 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);
+ * console.log(`Correlation: ${corr.correlation}`);
+ * ```
+ */
+class AnalyticsResource {
+    constructor(client) {
+        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
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @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}`);
+     * ```
+     */
+    async performance(options) {
+        const params = {};
+        if (options?.commodity)
+            params.commodity = options.commodity;
+        if (options?.days)
+            params.days = options.days.toString();
+        return this.client["request"]("/v1/analytics/performance", params);
+    }
+    /**
+     * Get statistical analysis for a commodity
+     *
+     * Returns comprehensive statistical metrics including mean, median,
+     * standard deviation, and distribution characteristics.
+     *
+     * @param commodity - Commodity code to analyze
+     * @param days - Number of days to analyze (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}`);
+     * ```
+     */
+    async statistics(commodity, days) {
+        if (!commodity || typeof commodity !== "string") {
+            throw new errors_js_1.ValidationError("Commodity code must be a non-empty string");
+        }
+        const params = { commodity };
+        if (days)
+            params.days = days.toString();
+        return this.client["request"]("/v1/analytics/statistics", params);
+    }
+    /**
+     * Analyze correlation between two commodities
+     *
+     * Calculates the Pearson correlation coefficient to measure how closely
+     * two commodities move together.
+     *
+     * @param commodity1 - First commodity code
+     * @param commodity2 - Second commodity code
+     * @param days - Number of days to analyze (default: 30)
+     * @returns Correlation analysis
+     *
+     * @throws {NotFoundError} If either commodity not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @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}`);
+     * ```
+     */
+    async correlation(commodity1, commodity2, days) {
+        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");
+        }
+        const params = {
+            commodity1,
+            commodity2,
+        };
+        if (days)
+            params.days = days.toString();
+        return this.client["request"]("/v1/analytics/correlation", params);
+    }
+    /**
+     * Analyze price trend for a commodity
+     *
+     * Detects trend direction, strength, and key levels (support/resistance).
+     *
+     * @param commodity - Commodity code to analyze
+     * @param days - Number of days to analyze (default: 30)
+     * @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}`);
+     * ```
+     */
+    async trend(commodity, days) {
+        if (!commodity || typeof commodity !== "string") {
+            throw new errors_js_1.ValidationError("Commodity code must be a non-empty string");
+        }
+        const params = { commodity };
+        if (days)
+            params.days = days.toString();
+        return this.client["request"]("/v1/analytics/trend", params);
+    }
+    /**
+     * Analyze spread between two commodities
+     *
+     * Calculates current spread and compares to historical patterns.
+     *
+     * @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
+     *
+     * @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}`);
+     * ```
+     */
+    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,
+        });
+    }
+    /**
+     * Get price forecast for a commodity
+     *
+     * Returns forecasted prices with confidence intervals.
+     *
+     * @param commodity - Commodity code to forecast
+     * @returns Price forecast
+     *
+     * @throws {NotFoundError} If commodity not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @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})`);
+     * });
+     * ```
+     */
+    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,
+        });
+    }
+}
+exports.AnalyticsResource = AnalyticsResource;

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

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * Bunker Fuels Resource
+ *
+ * Access bunker fuel prices at major ports worldwide, including VLSFO, MGO,
+ * and IFO380. Compare prices across ports and track historical trends.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BunkerFuelsResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Bunker Fuels Resource
+ *
+ * Access bunker fuel prices at major ports worldwide. Track VLSFO, MGO, and
+ * IFO380 prices, compare across ports, and analyze historical trends.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get all bunker fuel prices
+ * const prices = await client.bunkerFuels.all();
+ *
+ * // Get prices for specific port
+ * const singapore = await client.bunkerFuels.port('SIN');
+ * console.log(`Singapore VLSFO: $${singapore.prices.VLSFO}/MT`);
+ *
+ * // Compare prices across ports
+ * const comparison = await client.bunkerFuels.compare(['SIN', 'RTM', 'HOU']);
+ * ```
+ */
+class BunkerFuelsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get all current bunker fuel prices
+     *
+     * Returns prices for all tracked ports and fuel types.
+     *
+     * @returns Array of bunker fuel prices
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const prices = await client.bunkerFuels.all();
+     * prices.forEach(price => {
+     *   console.log(`${price.port_name} ${price.fuel_type}: $${price.price}/${price.unit}`);
+     * });
+     * ```
+     */
+    async all() {
+        const response = await this.client["request"]("/v1/bunker-fuels", {});
+        return Array.isArray(response) ? response : response.prices;
+    }
+    /**
+     * Get bunker fuel prices for a specific port
+     *
+     * @param code - Port code (e.g., "SIN" for Singapore, "RTM" for Rotterdam)
+     * @returns Port-specific prices across fuel types
+     *
+     * @throws {NotFoundError} If port code not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const singapore = await client.bunkerFuels.port('SIN');
+     * console.log(`Singapore Bunker Prices (${singapore.timestamp}):`);
+     * console.log(`VLSFO: $${singapore.prices.VLSFO}/${singapore.unit}`);
+     * console.log(`MGO: $${singapore.prices.MGO}/${singapore.unit}`);
+     * ```
+     */
+    async port(code) {
+        if (!code || typeof code !== "string") {
+            throw new errors_js_1.ValidationError("Port code must be a non-empty string");
+        }
+        return this.client["request"](`/v1/bunker-fuels/ports/${code}`, {});
+    }
+    /**
+     * Compare prices across multiple ports
+     *
+     * @param ports - Array of port codes to compare
+     * @returns Price comparison data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const comparison = await client.bunkerFuels.compare(['SIN', 'RTM', 'HOU', 'FUJ']);
+     *
+     * console.log(`Comparing ${comparison.fuel_type} prices:`);
+     * comparison.ports.forEach((port, index) => {
+     *   console.log(`${index + 1}. ${port.port_name}: $${port.price}`);
+     * });
+     * ```
+     */
+    async compare(ports) {
+        if (!Array.isArray(ports) || ports.length === 0) {
+            throw new errors_js_1.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
+     *
+     * Returns spreads between different fuel grades (e.g., VLSFO-IFO380).
+     *
+     * @returns Fuel price spreads
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const spreads = await client.bunkerFuels.spreads();
+     * spreads.spreads.forEach(spread => {
+     *   console.log(`${spread.fuel1}-${spread.fuel2} spread: $${spread.average_spread}`);
+     * });
+     * ```
+     */
+    async spreads() {
+        return this.client["request"]("/v1/bunker-fuels/spreads", {});
+    }
+    /**
+     * Get historical bunker fuel prices
+     *
+     * @param port - Port code (e.g., "SIN", "RTM")
+     * @param fuelType - Fuel type (e.g., "VLSFO", "MGO", "IFO380")
+     * @param options - Date range filters
+     * @returns Array of historical prices
+     *
+     * @throws {NotFoundError} If port or fuel type not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const history = await client.bunkerFuels.historical('SIN', 'VLSFO', {
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31'
+     * });
+     *
+     * history.forEach(point => {
+     *   console.log(`${point.date}: $${point.price}/${point.unit}`);
+     * });
+     * ```
+     */
+    async historical(port, fuelType, 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,
+        };
+        if (options?.startDate)
+            params.start_date = options.startDate;
+        if (options?.endDate)
+            params.end_date = options.endDate;
+        const response = await this.client["request"]("/v1/bunker-fuels/historical", params);
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Export bunker fuel data
+     *
+     * Export bunker fuel prices in specified format (CSV, JSON, Excel).
+     *
+     * @param format - Export format (default: "csv")
+     * @returns Export data or download URL
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * // Export as CSV
+     * const csvData = await client.bunkerFuels.export('csv');
+     *
+     * // Export as JSON
+     * const jsonData = await client.bunkerFuels.export('json');
+     * ```
+     */
+    async export(format) {
+        const params = {};
+        if (format)
+            params.format = format;
+        return this.client["request"]("/v1/bunker-fuels/export", params);
+    }
+}
+exports.BunkerFuelsResource = BunkerFuelsResource;

package/dist/cjs/resources/commodities.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * Commodities Resource
+ *
+ * Get metadata about supported commodities and categories.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommoditiesResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Commodities Resource
+ *
+ * Access metadata about supported commodities and categories.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // List all commodities
+ * const response = await client.commodities.list();
+ * console.log(`${response.commodities.length} commodities available`);
+ *
+ * // Get specific commodity
+ * const wti = await client.commodities.get('WTI_USD');
+ * console.log(`${wti.name}: ${wti.description}`);
+ *
+ * // Get categories
+ * const categories = await client.commodities.categories();
+ * console.log(`Oil category has ${categories.oil.commodities.length} commodities`);
+ * ```
+ */
+class CommoditiesResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all supported commodities
+     *
+     * Returns metadata for all commodities available in the API, including
+     * codes, names, units, and validation ranges.
+     *
+     * @returns Object containing array of commodities
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const response = await client.commodities.list();
+     *
+     * response.commodities.forEach(commodity => {
+     *   console.log(`${commodity.code}: ${commodity.name} (${commodity.unit})`);
+     * });
+     * ```
+     */
+    async list() {
+        return this.client["request"]("/v1/commodities", {});
+    }
+    /**
+     * Get metadata for a specific commodity by code
+     *
+     * @param code - Commodity code (e.g., "WTI_USD", "BRENT_CRUDE_USD")
+     * @returns Commodity metadata object
+     *
+     * @throws {NotFoundError} If commodity code is invalid
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const commodity = await client.commodities.get('WTI_USD');
+     * console.log(`Name: ${commodity.name}`);
+     * console.log(`Unit: ${commodity.unit}`);
+     * console.log(`Currency: ${commodity.currency}`);
+     * console.log(`Category: ${commodity.category}`);
+     * ```
+     */
+    async get(code) {
+        if (!code || typeof code !== "string") {
+            throw new errors_js_1.ValidationError("Commodity code must be a non-empty string");
+        }
+        return this.client["request"](`/v1/commodities/${code}`, {});
+    }
+    /**
+     * Get all commodity categories with their commodities
+     *
+     * Returns commodities grouped by category (oil, gas, renewable, etc.).
+     * Useful for building navigation or filtering UIs.
+     *
+     * @returns Object with category keys mapped to category objects
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const categories = await client.commodities.categories();
+     *
+     * // Access by category key
+     * console.log(`Oil: ${categories.oil.name}`);
+     * console.log(`Commodities: ${categories.oil.commodities.length}`);
+     *
+     * // Iterate all categories
+     * Object.entries(categories).forEach(([key, category]) => {
+     *   console.log(`${category.name}: ${category.commodities.length} commodities`);
+     * });
+     * ```
+     */
+    async categories() {
+        return this.client["request"]("/v1/commodities/categories", {});
+    }
+}
+exports.CommoditiesResource = CommoditiesResource;

package/dist/cjs/resources/data-quality.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Data Quality Resource
+ *
+ * Access data quality metrics, reports, and monitoring for commodity price data.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataQualityResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Data Quality Resource
+ *
+ * Monitor data quality metrics and access detailed quality reports for
+ * commodity price data sources.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get quality summary
+ * const summary = await client.dataQuality.summary();
+ * console.log(`Overall quality: ${summary.overall_score}/100`);
+ * console.log(`Sources monitored: ${summary.sources_monitored}`);
+ *
+ * // Get all reports
+ * const reports = await client.dataQuality.reports();
+ * reports.forEach(report => {
+ *   console.log(`${report.name}: ${report.status}`);
+ * });
+ * ```
+ */
+class DataQualityResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get data quality summary
+     *
+     * Returns overall data quality metrics and recent alerts.
+     *
+     * @returns Data quality summary
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const summary = await client.dataQuality.summary();
+     *
+     * console.log(`Overall score: ${summary.overall_score}/100`);
+     * console.log(`Completeness: ${summary.breakdown.completeness}%`);
+     * console.log(`Timeliness: ${summary.breakdown.timeliness}%`);
+     * console.log(`Accuracy: ${summary.breakdown.accuracy}%`);
+     * console.log(`Consistency: ${summary.breakdown.consistency}%`);
+     *
+     * if (summary.recent_alerts && summary.recent_alerts.length > 0) {
+     *   console.log('\nRecent Alerts:');
+     *   summary.recent_alerts.forEach(alert => {
+     *     console.log(`[${alert.severity.toUpperCase()}] ${alert.message}`);
+     *   });
+     * }
+     * ```
+     */
+    async summary() {
+        return this.client["request"]("/v1/data-quality/summary", {});
+    }
+    /**
+     * Get all data quality reports
+     *
+     * Returns metadata for all available quality reports.
+     *
+     * @returns Array of report metadata
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const reports = await client.dataQuality.reports();
+     *
+     * console.log(`${reports.length} quality reports available:\n`);
+     * reports.forEach(report => {
+     *   console.log(`${report.name}`);
+     *   console.log(`  Code: ${report.code}`);
+     *   console.log(`  Scope: ${report.scope}`);
+     *   console.log(`  Status: ${report.status}`);
+     *   console.log(`  Last generated: ${report.last_generated}\n`);
+     * });
+     * ```
+     */
+    async reports() {
+        const response = await this.client["request"]("/v1/data-quality/reports", {});
+        return Array.isArray(response) ? response : response.reports;
+    }
+    /**
+     * Get detailed data quality report
+     *
+     * Returns comprehensive quality analysis for a specific source or commodity.
+     *
+     * @param code - Report code (e.g., "WTI_USD", "BRENT_CRUDE_USD", "EIA")
+     * @returns Detailed quality report
+     *
+     * @throws {NotFoundError} If report code not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const report = await client.dataQuality.report('WTI_USD');
+     *
+     * console.log(`Report: ${report.name}`);
+     * console.log(`Scope: ${report.scope}`);
+     * console.log(`Period: ${report.period.start} to ${report.period.end}\n`);
+     *
+     * console.log('Metrics:');
+     * console.log(`  Completeness: ${report.metrics.completeness}%`);
+     * console.log(`  Timeliness: ${report.metrics.timeliness}%`);
+     * console.log(`  Accuracy: ${report.metrics.accuracy}%`);
+     * console.log(`  Consistency: ${report.metrics.consistency}%`);
+     *
+     * if (report.issues && report.issues.length > 0) {
+     *   console.log('\nIssues:');
+     *   report.issues.forEach(issue => {
+     *     console.log(`  [${issue.severity.toUpperCase()}] ${issue.description}`);
+     *   });
+     * }
+     *
+     * if (report.recommendations && report.recommendations.length > 0) {
+     *   console.log('\nRecommendations:');
+     *   report.recommendations.forEach(rec => {
+     *     console.log(`  - ${rec}`);
+     *   });
+     * }
+     * ```
+     */
+    async report(code) {
+        if (!code || typeof code !== "string") {
+            throw new errors_js_1.ValidationError("Report code must be a non-empty string");
+        }
+        return this.client["request"](`/v1/data-quality/reports/${code}`, {});
+    }
+}
+exports.DataQualityResource = DataQualityResource;