oilpriceapi 0.5.3 → 0.7.0

package/dist/resources/analytics.js

@@ -0,0 +1,221 @@
+/**
+ * Analytics Resource
+ *
+ * Access advanced analytics including performance metrics, statistical analysis,
+ * correlations, trend detection, spreads, and forecasts.
+ */
+/**
+ * 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}`);
+ * ```
+ */
+export 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 Error("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 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");
+        }
+        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 Error("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 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,
+        });
+    }
+    /**
+     * 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 Error("Commodity code must be a non-empty string");
+        }
+        return this.client["request"]("/v1/analytics/forecast", {
+            commodity,
+        });
+    }
+}

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

@@ -0,0 +1,270 @@
+/**
+ * Bunker Fuels Resource
+ *
+ * Access bunker fuel prices at major ports worldwide, including VLSFO, MGO,
+ * and IFO380. Compare prices across ports and track historical trends.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Bunker fuel price data
+ */
+export interface BunkerFuelPrice {
+    /** Port code */
+    port: string;
+    /** Port name */
+    port_name?: string;
+    /** Fuel type (e.g., "VLSFO", "MGO", "IFO380") */
+    fuel_type: string;
+    /** Price per metric ton */
+    price: number;
+    /** Currency code (typically "USD") */
+    currency: string;
+    /** Unit (typically "MT" for metric ton) */
+    unit: string;
+    /** ISO timestamp when price was recorded */
+    timestamp: string;
+    /** Price change from previous day */
+    change?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Port-specific bunker fuel prices
+ */
+export interface PortBunkerPrices {
+    /** Port code */
+    port: string;
+    /** Port name */
+    port_name: string;
+    /** Geographic region */
+    region?: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Fuel prices by type */
+    prices: {
+        /** VLSFO price */
+        VLSFO?: number;
+        /** MGO price */
+        MGO?: number;
+        /** IFO380 price */
+        IFO380?: number;
+        /** Other fuel types */
+        [fuelType: string]: number | undefined;
+    };
+    /** Currency code */
+    currency: string;
+    /** Unit of measurement */
+    unit: string;
+}
+/**
+ * Price comparison between ports
+ */
+export interface PortPriceComparison {
+    /** Fuel type being compared */
+    fuel_type: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Array of port prices */
+    ports: Array<{
+        /** Port code */
+        port: string;
+        /** Port name */
+        port_name: string;
+        /** Price */
+        price: number;
+        /** Rank (1 = cheapest) */
+        rank?: number;
+    }>;
+    /** Currency code */
+    currency: string;
+    /** Unit of measurement */
+    unit: string;
+}
+/**
+ * Bunker fuel price spreads
+ */
+export interface BunkerFuelSpreads {
+    /** ISO timestamp */
+    timestamp: string;
+    /** Spreads between fuel grades */
+    spreads: Array<{
+        /** High-grade fuel */
+        fuel1: string;
+        /** Low-grade fuel */
+        fuel2: string;
+        /** Average spread across ports */
+        average_spread: number;
+        /** Spread range */
+        min_spread: number;
+        max_spread: number;
+    }>;
+    /** Currency code */
+    currency: string;
+}
+/**
+ * Historical bunker fuel price data
+ */
+export interface HistoricalBunkerPrice {
+    /** Date in YYYY-MM-DD format */
+    date: string;
+    /** Price */
+    price: number;
+    /** Currency code */
+    currency: string;
+    /** Unit of measurement */
+    unit: string;
+}
+/**
+ * Options for historical bunker fuel query
+ */
+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;
+}
+/**
+ * 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']);
+ * ```
+ */
+export declare class BunkerFuelsResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * 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}`);
+     * });
+     * ```
+     */
+    all(): Promise<BunkerFuelPrice[]>;
+    /**
+     * 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}`);
+     * ```
+     */
+    port(code: string): Promise<PortBunkerPrices>;
+    /**
+     * 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}`);
+     * });
+     * ```
+     */
+    compare(ports: string[]): Promise<PortPriceComparison>;
+    /**
+     * 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}`);
+     * });
+     * ```
+     */
+    spreads(): Promise<BunkerFuelSpreads>;
+    /**
+     * 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}`);
+     * });
+     * ```
+     */
+    historical(port: string, fuelType: string, options?: HistoricalBunkerOptions): Promise<HistoricalBunkerPrice[]>;
+    /**
+     * 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');
+     * ```
+     */
+    export(format?: string): Promise<any>;
+}

package/dist/resources/bunker-fuels.js

@@ -0,0 +1,191 @@
+/**
+ * Bunker Fuels Resource
+ *
+ * Access bunker fuel prices at major ports worldwide, including VLSFO, MGO,
+ * and IFO380. Compare prices across ports and track historical trends.
+ */
+/**
+ * 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']);
+ * ```
+ */
+export 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 Error("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 Error("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 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");
+        }
+        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);
+    }
+}