oilpriceapi 0.6.0 → 0.8.2

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,192 @@
+/**
+ * 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 { ValidationError } from "../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']);
+ * ```
+ */
+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 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 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 ValidationError("Port code must be a non-empty string");
+        }
+        if (!fuelType || typeof fuelType !== "string") {
+            throw new 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);
+    }
+}

package/dist/resources/commodities.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Commodities Resource
+ *
+ * Get metadata about supported commodities and categories.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Commodity metadata
+ */
+export interface Commodity {
+    /** Unique commodity identifier */
+    code: string;
+    /** Human-readable commodity name */
+    name: string;
+    /** Base currency for pricing */
+    currency: string;
+    /** Commodity category (e.g., "oil", "gas", "renewable") */
+    category: string;
+    /** Detailed description */
+    description?: string;
+    /** Unit of measurement (e.g., "barrel", "gallon") */
+    unit: string;
+    /** Detailed unit description */
+    unit_description?: string;
+    /** Storage multiplier for price values */
+    multiplier?: number;
+    /** Price validation ranges */
+    validation?: {
+        min: number;
+        max: number;
+    };
+    /** Threshold for significant price change alerts */
+    price_change_threshold?: number;
+}
+/**
+ * Response from /v1/commodities endpoint
+ */
+export interface CommoditiesResponse {
+    commodities: Commodity[];
+}
+/**
+ * Category with its commodities
+ */
+export interface CommodityCategory {
+    name: string;
+    commodities: Commodity[];
+}
+/**
+ * Response from /v1/commodities/categories endpoint
+ */
+export interface CategoriesResponse {
+    [categoryKey: string]: CommodityCategory;
+}
+/**
+ * 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`);
+ * ```
+ */
+export declare class CommoditiesResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * 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})`);
+     * });
+     * ```
+     */
+    list(): Promise<CommoditiesResponse>;
+    /**
+     * 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}`);
+     * ```
+     */
+    get(code: string): Promise<Commodity>;
+    /**
+     * 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`);
+     * });
+     * ```
+     */
+    categories(): Promise<CategoriesResponse>;
+}