oilpriceapi 0.7.0 → 0.8.2

package/dist/client.js

@@ -41,11 +41,11 @@ import { SDK_VERSION, SDK_NAME, buildUserAgent } from "./version.js";
  * ```
  */
 export class OilPriceAPI {
-    constructor(config) {
-        if (!config.apiKey) {
-            throw new OilPriceAPIError("API key is required");
+    constructor(config = {}) {
+        this.apiKey = config.apiKey || process.env.OILPRICEAPI_KEY || "";
+        if (!this.apiKey) {
+            throw new OilPriceAPIError("API key required. Set OILPRICEAPI_KEY env var or pass apiKey in config.");
         }
-        this.apiKey = config.apiKey;
         this.baseUrl = config.baseUrl || "https://api.oilpriceapi.com";
         this.retries = config.retries !== undefined ? config.retries : 3;
         this.retryDelay = config.retryDelay || 1000;
@@ -123,9 +123,11 @@ export class OilPriceAPI {
         return false;
     }
     /**
-     * Internal method to make HTTP requests with retry and timeout
+     * Internal method to make HTTP requests with retry and timeout.
+     * Supports all HTTP methods (GET, POST, PATCH, DELETE) with consistent
+     * retry logic, timeout handling, and typed error responses.
      */
-    async request(endpoint, params) {
+    async request(endpoint, params, options) {
         // Build URL with query parameters
         const url = new URL(`${this.baseUrl}${endpoint}`);
         if (params) {
@@ -163,11 +165,15 @@ export class OilPriceAPI {
                     if (this.appName) {
                         headers["X-App-Name"] = this.appName;
                     }
-                    const response = await fetch(url.toString(), {
-                        method: "GET",
+                    const fetchOptions = {
+                        method: options?.method || "GET",
                         headers,
                         signal: controller.signal,
-                    });
+                    };
+                    if (options?.body !== undefined) {
+                        fetchOptions.body = JSON.stringify(options.body);
+                    }
+                    const response = await fetch(url.toString(), fetchOptions);
                     clearTimeout(timeoutId);
                     this.log(`Response: ${response.status} ${response.statusText}`);
                     // Handle error responses
@@ -177,8 +183,7 @@ export class OilPriceAPI {
                         // Try to parse JSON error response
                         try {
                             const errorJson = JSON.parse(errorBody);
-                            errorMessage =
-                                errorJson.message || errorJson.error || errorMessage;
+                            errorMessage = errorJson.message || errorJson.error || errorMessage;
                         }
                         catch {
                             // Use default error message if response isn't JSON
@@ -209,8 +214,14 @@ export class OilPriceAPI {
                                 throw new OilPriceAPIError(errorMessage, response.status, "HTTP_ERROR");
                         }
                     }
+                    // Handle empty responses (e.g., 204 No Content from DELETE)
+                    const responseText = await response.text();
+                    if (!responseText) {
+                        this.log("Empty response body");
+                        return {};
+                    }
                     // Parse successful response
-                    const responseData = await response.json();
+                    const responseData = JSON.parse(responseText);
                     this.log("Response data received", {
                         status: responseData.status,
                         hasData: !!responseData.data,
@@ -230,9 +241,9 @@ export class OilPriceAPI {
                             return [responseData.data];
                         }
                     }
-                    // Fallback - return data as-is
+                    // Fallback - return data as-is (used by resource mutations, alerts, webhooks, etc.)
                     this.log("Returning data as-is");
-                    return responseData.data;
+                    return (responseData.data !== undefined ? responseData.data : responseData);
                 }
                 catch (error) {
                     // Handle abort (timeout)
@@ -353,6 +364,51 @@ export class OilPriceAPI {
         // Solution: Use /v1/prices/past_year which uses direct WHERE clauses
         return this.request("/v1/prices/past_year", params);
     }
+    /**
+     * Paginate through historical prices automatically.
+     *
+     * Returns an async generator that yields pages of prices, fetching
+     * the next page only when needed. Avoids loading all data into memory.
+     *
+     * @param options - Same options as getHistoricalPrices, plus perPage (default: 100)
+     *
+     * @example
+     * ```typescript
+     * // Iterate through all pages
+     * for await (const page of client.paginateHistoricalPrices({
+     *   commodity: 'BRENT_CRUDE_USD',
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31',
+     *   perPage: 100,
+     * })) {
+     *   console.log(`Got ${page.length} prices`);
+     *   // Process each page...
+     * }
+     *
+     * // Or collect all prices
+     * const allPrices: Price[] = [];
+     * for await (const page of client.paginateHistoricalPrices({ commodity: 'WTI_USD' })) {
+     *   allPrices.push(...page);
+     * }
+     * ```
+     */
+    async *paginateHistoricalPrices(options) {
+        const perPage = options?.perPage || 100;
+        let page = 1;
+        while (true) {
+            const results = await this.getHistoricalPrices({
+                ...options,
+                page,
+                perPage,
+            });
+            if (results.length === 0)
+                break;
+            yield results;
+            if (results.length < perPage)
+                break;
+            page++;
+        }
+    }
     /**
      * Get prices from your connected data sources (BYOS)
      *

package/dist/errors.d.ts

@@ -40,6 +40,12 @@ export declare class NotFoundError extends OilPriceAPIError {
 export declare class ServerError extends OilPriceAPIError {
     constructor(message?: string, statusCode?: number);
 }
+/**
+ * Thrown when SDK-side input validation fails
+ */
+export declare class ValidationError extends OilPriceAPIError {
+    constructor(message: string);
+}
 /**
  * Thrown when request exceeds timeout
  */

package/dist/errors.js

@@ -4,7 +4,7 @@
 export class OilPriceAPIError extends Error {
     constructor(message, statusCode, code) {
         super(message);
-        this.name = 'OilPriceAPIError';
+        this.name = "OilPriceAPIError";
         this.statusCode = statusCode;
         this.code = code;
         // Maintains proper stack trace for where our error was thrown (only available on V8)
@@ -17,18 +17,18 @@ export class OilPriceAPIError extends Error {
  * Thrown when API authentication fails (401)
  */
 export class AuthenticationError extends OilPriceAPIError {
-    constructor(message = 'Invalid API key') {
-        super(message, 401, 'AUTHENTICATION_ERROR');
-        this.name = 'AuthenticationError';
+    constructor(message = "Invalid API key") {
+        super(message, 401, "AUTHENTICATION_ERROR");
+        this.name = "AuthenticationError";
     }
 }
 /**
  * Thrown when rate limit is exceeded (429)
  */
 export class RateLimitError extends OilPriceAPIError {
-    constructor(message = 'Rate limit exceeded', retryAfter) {
-        super(message, 429, 'RATE_LIMIT_ERROR');
-        this.name = 'RateLimitError';
+    constructor(message = "Rate limit exceeded", retryAfter) {
+        super(message, 429, "RATE_LIMIT_ERROR");
+        this.name = "RateLimitError";
         this.retryAfter = retryAfter;
     }
 }
@@ -36,26 +36,35 @@ export class RateLimitError extends OilPriceAPIError {
  * Thrown when requested resource is not found (404)
  */
 export class NotFoundError extends OilPriceAPIError {
-    constructor(message = 'Resource not found') {
-        super(message, 404, 'NOT_FOUND_ERROR');
-        this.name = 'NotFoundError';
+    constructor(message = "Resource not found") {
+        super(message, 404, "NOT_FOUND_ERROR");
+        this.name = "NotFoundError";
     }
 }
 /**
  * Thrown when server returns 5xx error
  */
 export class ServerError extends OilPriceAPIError {
-    constructor(message = 'Internal server error', statusCode = 500) {
-        super(message, statusCode, 'SERVER_ERROR');
-        this.name = 'ServerError';
+    constructor(message = "Internal server error", statusCode = 500) {
+        super(message, statusCode, "SERVER_ERROR");
+        this.name = "ServerError";
+    }
+}
+/**
+ * Thrown when SDK-side input validation fails
+ */
+export class ValidationError extends OilPriceAPIError {
+    constructor(message) {
+        super(message, undefined, "VALIDATION_ERROR");
+        this.name = "ValidationError";
     }
 }
 /**
  * Thrown when request exceeds timeout
  */
 export class TimeoutError extends OilPriceAPIError {
-    constructor(message = 'Request timeout', timeout) {
-        super(`${message} (${timeout}ms)`, undefined, 'TIMEOUT_ERROR');
-        this.name = 'TimeoutError';
+    constructor(message = "Request timeout", timeout) {
+        super(`${message} (${timeout}ms)`, undefined, "TIMEOUT_ERROR");
+        this.name = "TimeoutError";
     }
 }

package/dist/index.d.ts

@@ -15,13 +15,13 @@ export type { StorageData, HistoricalStorageData, HistoricalStorageOptions, } fr
 export type { RigCountData, HistoricalRigCountData, HistoricalRigCountOptions, RigCountTrend, RigCountSummary, } from "./resources/rig-counts.js";
 export type { BunkerFuelPrice, PortBunkerPrices, PortPriceComparison, BunkerFuelSpreads, HistoricalBunkerPrice, HistoricalBunkerOptions, } from "./resources/bunker-fuels.js";
 export type { PerformanceMetrics, PerformanceOptions, StatisticalAnalysis, CorrelationAnalysis, TrendAnalysis, SpreadAnalysis, ForecastPoint, PriceForecast as AnalyticsPriceForecast, } from "./resources/analytics.js";
-export type { MonthlyForecast, ForecastAccuracy, ArchivedForecast, } from "./resources/forecasts.js";
+export type { MonthlyForecast, ForecastAccuracy, ArchivedForecast } from "./resources/forecasts.js";
 export type { DataQualitySummary, DataQualityReportMeta, DataQualityReport, } from "./resources/data-quality.js";
 export type { DrillingIntelligenceData, LatestDrillingData, DrillingSummary, DrillingTrend, FracSpreadData, WellPermitData, DUCWellData, CompletionData, WellsDrilledData, BasinDrillingData, } from "./resources/drilling.js";
 export type { WellTimelineEvent, WellTimeline, RigCountRecord, RigCountByBasin, RigCountByState, HistoricalRigCount, OilInventoryRecord, OilInventorySummary, InventoryByProduct, HistoricalInventory, CushingInventory, OPECProductionRecord, TotalOPECProduction, ProductionByCountry, HistoricalProduction, TopProducer, DrillingProductivityRecord, DrillingProductivitySummary, DUCWellInventory, ProductivityByBasin, HistoricalProductivity, ProductivityTrend, ForecastRecord, ForecastSummary, PriceForecast, ProductionForecast, HistoricalForecast, ForecastComparison, WellPermitRecord, WellPermitSummary, PermitsByState, PermitsByOperator, PermitsByFormation, WellPermitSearchQuery, FracFocusRecord, FracFocusSummary, DisclosuresByState, DisclosuresByOperator, ChemicalUsage, WellChemical, FracFocusSearchQuery, } from "./resources/ei/index.js";
 export type { WebhookEndpoint, CreateWebhookParams, UpdateWebhookParams, WebhookTestResponse as WebhookTestResult, WebhookEvent, } from "./resources/webhooks.js";
 export type { DataSourceType, DataSourceStatus, DataSource, CreateDataSourceParams, UpdateDataSourceParams, DataSourceTestResponse, DataSourceLog, DataSourceHealth, CredentialRotationResponse, } from "./resources/data-sources.js";
-export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, TimeoutError, } from "./errors.js";
+export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, ValidationError, TimeoutError, } from "./errors.js";
 export { DieselResource } from "./resources/diesel.js";
 export { AlertsResource } from "./resources/alerts.js";
 export { CommoditiesResource } from "./resources/commodities.js";
@@ -36,3 +36,17 @@ export { DrillingIntelligenceResource } from "./resources/drilling.js";
 export { EnergyIntelligenceResource, EIRigCountsResource, EIOilInventoriesResource, EIOPECProductionResource, EIDrillingProductivityResource, EIForecastsResource, EIWellPermitsResource, EIFracFocusResource, } from "./resources/ei/index.js";
 export { WebhooksResource } from "./resources/webhooks.js";
 export { DataSourcesResource } from "./resources/data-sources.js";
+/**
+ * Standalone webhook signature verification.
+ *
+ * Convenience function for verifying webhook signatures without
+ * instantiating a full client.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from 'oilpriceapi';
+ *
+ * const isValid = verifyWebhookSignature(rawBody, signatureHeader, secret);
+ * ```
+ */
+export declare function verifyWebhookSignature(payload: string | Buffer, signature: string, secret: string): boolean;

package/dist/index.js

@@ -5,9 +5,10 @@
  *
  * @packageDocumentation
  */
+import { createHmac, timingSafeEqual } from "node:crypto";
 export { OilPriceAPI } from "./client.js";
 export { SDK_VERSION, SDK_NAME } from "./version.js";
-export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, TimeoutError, } from "./errors.js";
+export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, ValidationError, TimeoutError, } from "./errors.js";
 export { DieselResource } from "./resources/diesel.js";
 export { AlertsResource } from "./resources/alerts.js";
 export { CommoditiesResource } from "./resources/commodities.js";
@@ -22,3 +23,25 @@ export { DrillingIntelligenceResource } from "./resources/drilling.js";
 export { EnergyIntelligenceResource, EIRigCountsResource, EIOilInventoriesResource, EIOPECProductionResource, EIDrillingProductivityResource, EIForecastsResource, EIWellPermitsResource, EIFracFocusResource, } from "./resources/ei/index.js";
 export { WebhooksResource } from "./resources/webhooks.js";
 export { DataSourcesResource } from "./resources/data-sources.js";
+/**
+ * Standalone webhook signature verification.
+ *
+ * Convenience function for verifying webhook signatures without
+ * instantiating a full client.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from 'oilpriceapi';
+ *
+ * const isValid = verifyWebhookSignature(rawBody, signatureHeader, secret);
+ * ```
+ */
+export function verifyWebhookSignature(payload, signature, secret) {
+    const expectedSignature = "sha256=" + createHmac("sha256", secret).update(payload).digest("hex");
+    try {
+        return timingSafeEqual(Buffer.from(expectedSignature), Buffer.from(signature));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/resources/alerts.js

@@ -3,6 +3,7 @@
  *
  * Manage price alert configurations for automated notifications.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Price Alerts Resource
  *
@@ -100,7 +101,7 @@ export class AlertsResource {
      */
     async get(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Alert ID must be a non-empty string");
+            throw new ValidationError("Alert ID must be a non-empty string");
         }
         const response = await this.client["request"](`/v1/alerts/${id}`, {});
         // API returns object directly, but handle both formats for compatibility
@@ -146,16 +147,16 @@ export class AlertsResource {
     async create(params) {
         // Validate required fields
         if (!params.name || typeof params.name !== "string") {
-            throw new Error("Alert name is required and must be a string");
+            throw new ValidationError("Alert name is required and must be a string");
         }
         if (params.name.length < 1 || params.name.length > 100) {
-            throw new Error("Alert name must be 1-100 characters");
+            throw new ValidationError("Alert name must be 1-100 characters");
         }
         if (!params.commodity_code || typeof params.commodity_code !== "string") {
-            throw new Error("Commodity code is required and must be a string");
+            throw new ValidationError("Commodity code is required and must be a string");
         }
         if (!params.condition_operator) {
-            throw new Error("Condition operator is required");
+            throw new ValidationError("Condition operator is required");
         }
         const validOperators = [
             "greater_than",
@@ -165,39 +166,34 @@ export class AlertsResource {
             "less_than_or_equal",
         ];
         if (!validOperators.includes(params.condition_operator)) {
-            throw new Error(`Invalid operator. Must be one of: ${validOperators.join(", ")}`);
+            throw new ValidationError(`Invalid operator. Must be one of: ${validOperators.join(", ")}`);
         }
         if (typeof params.condition_value !== "number") {
-            throw new Error("Condition value must be a number");
+            throw new ValidationError("Condition value must be a number");
         }
         if (params.condition_value <= 0 || params.condition_value > 1000000) {
-            throw new Error("Condition value must be greater than 0 and less than or equal to 1,000,000");
+            throw new ValidationError("Condition value must be greater than 0 and less than or equal to 1,000,000");
         }
         // Validate optional fields
         if (params.webhook_url !== undefined) {
             if (typeof params.webhook_url !== "string") {
-                throw new Error("Webhook URL must be a string");
+                throw new ValidationError("Webhook URL must be a string");
             }
             if (params.webhook_url && !params.webhook_url.startsWith("https://")) {
-                throw new Error("Webhook URL must use HTTPS protocol");
+                throw new ValidationError("Webhook URL must use HTTPS protocol");
             }
         }
         if (params.cooldown_minutes !== undefined) {
             if (typeof params.cooldown_minutes !== "number") {
-                throw new Error("Cooldown minutes must be a number");
+                throw new ValidationError("Cooldown minutes must be a number");
             }
             if (params.cooldown_minutes < 0 || params.cooldown_minutes > 1440) {
-                throw new Error("Cooldown minutes must be between 0 and 1440 (24 hours)");
+                throw new ValidationError("Cooldown minutes must be between 0 and 1440 (24 hours)");
             }
         }
-        const url = `${this.client["baseUrl"]}/v1/alerts`;
-        const response = await fetch(url, {
+        const response = await this.client["request"]("/v1/alerts", {}, {
             method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({
+            body: {
                 price_alert: {
                     name: params.name,
                     commodity_code: params.commodity_code,
@@ -208,15 +204,9 @@ export class AlertsResource {
                     cooldown_minutes: params.cooldown_minutes ?? 60,
                     metadata: params.metadata,
                 },
-            }),
+            },
         });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to create alert: ${response.status} ${errorText}`);
-        }
-        const data = (await response.json());
-        // API returns object directly, but handle both formats for compatibility
-        return "alert" in data ? data.alert : data;
+        return "alert" in response ? response.alert : response;
     }
     /**
      * Update an existing price alert
@@ -251,14 +241,14 @@ export class AlertsResource {
      */
     async update(id, params) {
         if (!id || typeof id !== "string") {
-            throw new Error("Alert ID must be a non-empty string");
+            throw new ValidationError("Alert ID must be a non-empty string");
         }
         // Validate fields if provided
         if (params.name !== undefined) {
             if (typeof params.name !== "string" ||
                 params.name.length < 1 ||
                 params.name.length > 100) {
-                throw new Error("Alert name must be 1-100 characters");
+                throw new ValidationError("Alert name must be 1-100 characters");
             }
         }
         if (params.condition_operator !== undefined) {
@@ -270,48 +260,35 @@ export class AlertsResource {
                 "less_than_or_equal",
             ];
             if (!validOperators.includes(params.condition_operator)) {
-                throw new Error(`Invalid operator. Must be one of: ${validOperators.join(", ")}`);
+                throw new ValidationError(`Invalid operator. Must be one of: ${validOperators.join(", ")}`);
             }
         }
         if (params.condition_value !== undefined) {
             if (typeof params.condition_value !== "number") {
-                throw new Error("Condition value must be a number");
+                throw new ValidationError("Condition value must be a number");
             }
             if (params.condition_value <= 0 || params.condition_value > 1000000) {
-                throw new Error("Condition value must be greater than 0 and less than or equal to 1,000,000");
+                throw new ValidationError("Condition value must be greater than 0 and less than or equal to 1,000,000");
             }
         }
         if (params.webhook_url !== undefined && params.webhook_url !== null) {
             if (typeof params.webhook_url !== "string" ||
                 !params.webhook_url.startsWith("https://")) {
-                throw new Error("Webhook URL must be a valid HTTPS URL");
+                throw new ValidationError("Webhook URL must be a valid HTTPS URL");
             }
         }
         if (params.cooldown_minutes !== undefined) {
             if (typeof params.cooldown_minutes !== "number" ||
                 params.cooldown_minutes < 0 ||
                 params.cooldown_minutes > 1440) {
-                throw new Error("Cooldown minutes must be between 0 and 1440 (24 hours)");
+                throw new ValidationError("Cooldown minutes must be between 0 and 1440 (24 hours)");
             }
         }
-        const url = `${this.client["baseUrl"]}/v1/alerts/${id}`;
-        const response = await fetch(url, {
+        const response = await this.client["request"](`/v1/alerts/${id}`, {}, {
             method: "PATCH",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({
-                price_alert: params,
-            }),
+            body: { price_alert: params },
         });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to update alert: ${response.status} ${errorText}`);
-        }
-        const data = (await response.json());
-        // API returns object directly, but handle both formats for compatibility
-        return "alert" in data ? data.alert : data;
+        return "alert" in response ? response.alert : response;
     }
     /**
      * Delete a price alert
@@ -331,20 +308,9 @@ export class AlertsResource {
      */
     async delete(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Alert ID must be a non-empty string");
-        }
-        const url = `${this.client["baseUrl"]}/v1/alerts/${id}`;
-        const response = await fetch(url, {
-            method: "DELETE",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-        });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to delete alert: ${response.status} ${errorText}`);
+            throw new ValidationError("Alert ID must be a non-empty string");
         }
+        await this.client["request"](`/v1/alerts/${id}`, {}, { method: "DELETE" });
     }
     /**
      * Test an alert
@@ -369,21 +335,9 @@ export class AlertsResource {
      */
     async test(alertId) {
         if (!alertId || typeof alertId !== "string") {
-            throw new Error("Alert ID must be a non-empty string");
-        }
-        const url = `${this.client["baseUrl"]}/v1/alerts/${alertId}/test`;
-        const response = await fetch(url, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.client["apiKey"]}`,
-                "Content-Type": "application/json",
-            },
-        });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to test alert: ${response.status} ${errorText}`);
+            throw new ValidationError("Alert ID must be a non-empty string");
         }
-        return response.json();
+        return this.client["request"](`/v1/alerts/${alertId}/test`, {}, { method: "POST" });
     }
     /**
      * Get available alert triggers

package/dist/resources/analytics.js

@@ -4,6 +4,7 @@
  * Access advanced analytics including performance metrics, statistical analysis,
  * correlations, trend detection, spreads, and forecasts.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Analytics Resource
  *
@@ -83,7 +84,7 @@ export class AnalyticsResource {
      */
     async statistics(commodity, days) {
         if (!commodity || typeof commodity !== "string") {
-            throw new Error("Commodity code must be a non-empty string");
+            throw new ValidationError("Commodity code must be a non-empty string");
         }
         const params = { commodity };
         if (days)
@@ -114,10 +115,10 @@ export class AnalyticsResource {
      */
     async correlation(commodity1, commodity2, days) {
         if (!commodity1 || typeof commodity1 !== "string") {
-            throw new Error("First commodity code must be a non-empty string");
+            throw new ValidationError("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");
+            throw new ValidationError("Second commodity code must be a non-empty string");
         }
         const params = {
             commodity1,
@@ -149,7 +150,7 @@ export class AnalyticsResource {
      */
     async trend(commodity, days) {
         if (!commodity || typeof commodity !== "string") {
-            throw new Error("Commodity code must be a non-empty string");
+            throw new ValidationError("Commodity code must be a non-empty string");
         }
         const params = { commodity };
         if (days)
@@ -178,10 +179,10 @@ export class AnalyticsResource {
      */
     async spread(commodity1, commodity2) {
         if (!commodity1 || typeof commodity1 !== "string") {
-            throw new Error("First commodity code must be a non-empty string");
+            throw new ValidationError("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");
+            throw new ValidationError("Second commodity code must be a non-empty string");
         }
         return this.client["request"]("/v1/analytics/spread", {
             commodity1,
@@ -212,7 +213,7 @@ export class AnalyticsResource {
      */
     async forecast(commodity) {
         if (!commodity || typeof commodity !== "string") {
-            throw new Error("Commodity code must be a non-empty string");
+            throw new ValidationError("Commodity code must be a non-empty string");
         }
         return this.client["request"]("/v1/analytics/forecast", {
             commodity,

package/dist/resources/bunker-fuels.js

@@ -4,6 +4,7 @@
  * 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
  *
@@ -72,7 +73,7 @@ export class BunkerFuelsResource {
      */
     async port(code) {
         if (!code || typeof code !== "string") {
-            throw new Error("Port code must be a non-empty string");
+            throw new ValidationError("Port code must be a non-empty string");
         }
         return this.client["request"](`/v1/bunker-fuels/ports/${code}`, {});
     }
@@ -96,7 +97,7 @@ export class BunkerFuelsResource {
      */
     async compare(ports) {
         if (!Array.isArray(ports) || ports.length === 0) {
-            throw new Error("Ports must be a non-empty array of port codes");
+            throw new ValidationError("Ports must be a non-empty array of port codes");
         }
         return this.client["request"]("/v1/bunker-fuels/compare", {
             ports: ports.join(","),
@@ -147,10 +148,10 @@ export class BunkerFuelsResource {
      */
     async historical(port, fuelType, options) {
         if (!port || typeof port !== "string") {
-            throw new Error("Port code must be a non-empty string");
+            throw new ValidationError("Port code must be a non-empty string");
         }
         if (!fuelType || typeof fuelType !== "string") {
-            throw new Error("Fuel type must be a non-empty string");
+            throw new ValidationError("Fuel type must be a non-empty string");
         }
         const params = {
             port,

package/dist/resources/commodities.js

@@ -3,6 +3,7 @@
  *
  * Get metadata about supported commodities and categories.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Commodities Resource
  *
@@ -75,7 +76,7 @@ export class CommoditiesResource {
      */
     async get(code) {
         if (!code || typeof code !== "string") {
-            throw new Error("Commodity code must be a non-empty string");
+            throw new ValidationError("Commodity code must be a non-empty string");
         }
         return this.client["request"](`/v1/commodities/${code}`, {});
     }

package/dist/resources/data-quality.js

@@ -3,6 +3,7 @@
  *
  * Access data quality metrics, reports, and monitoring for commodity price data.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Data Quality Resource
  *
@@ -132,7 +133,7 @@ export class DataQualityResource {
      */
     async report(code) {
         if (!code || typeof code !== "string") {
-            throw new Error("Report code must be a non-empty string");
+            throw new ValidationError("Report code must be a non-empty string");
         }
         return this.client["request"](`/v1/data-quality/reports/${code}`, {});
     }