oilpriceapi 0.7.0 → 0.9.0

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

@@ -0,0 +1,210 @@
+"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() {
+        // 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;
+    }
+    /**
+     * 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 the bunker fuel price spread between two ports.
+     *
+     * 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.)
+     *
+     * @param options - `{ from, to, grade? }`
+     * @returns Port-to-port fuel price spread
+     *
+     * @throws {ValidationError} If from/to are missing
+     *
+     * @example
+     * ```typescript
+     * const spread = await client.bunkerFuels.spreads({ from: 'SIN', to: 'RTM', grade: 'VLSFO' });
+     * ```
+     */
+    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
+     *
+     * @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
+     *
+     * 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', {
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31'
+     * });
+     *
+     * history.forEach(point => {
+     *   console.log(`${point.date}: $${point.price}/${point.unit}`);
+     * });
+     * ```
+     */
+    async historical(port, options) {
+        if (!port || typeof port !== "string") {
+            throw new errors_js_1.ValidationError("Port code must be a non-empty string");
+        }
+        const params = {};
+        if (options?.startDate)
+            params.from = options.startDate;
+        if (options?.endDate)
+            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;
+    }
+    /**
+     * 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;