oilpriceapi 0.7.0 → 0.8.2

package/dist/cjs/index.js

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Official Node.js SDK for Oil Price API
+ *
+ * Get real-time and historical oil & commodity prices in your Node.js applications.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataSourcesResource = exports.WebhooksResource = exports.EIFracFocusResource = exports.EIWellPermitsResource = exports.EIForecastsResource = exports.EIDrillingProductivityResource = exports.EIOPECProductionResource = exports.EIOilInventoriesResource = exports.EIRigCountsResource = exports.EnergyIntelligenceResource = exports.DrillingIntelligenceResource = exports.DataQualityResource = exports.ForecastsResource = exports.AnalyticsResource = exports.BunkerFuelsResource = exports.RigCountsResource = exports.StorageResource = exports.FuturesResource = exports.CommoditiesResource = exports.AlertsResource = exports.DieselResource = exports.TimeoutError = exports.ValidationError = exports.ServerError = exports.NotFoundError = exports.RateLimitError = exports.AuthenticationError = exports.OilPriceAPIError = exports.SDK_NAME = exports.SDK_VERSION = exports.OilPriceAPI = void 0;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+const node_crypto_1 = require("node:crypto");
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "OilPriceAPI", { enumerable: true, get: function () { return client_js_1.OilPriceAPI; } });
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return version_js_1.SDK_VERSION; } });
+Object.defineProperty(exports, "SDK_NAME", { enumerable: true, get: function () { return version_js_1.SDK_NAME; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "OilPriceAPIError", { enumerable: true, get: function () { return errors_js_1.OilPriceAPIError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_js_1.RateLimitError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_js_1.NotFoundError; } });
+Object.defineProperty(exports, "ServerError", { enumerable: true, get: function () { return errors_js_1.ServerError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_js_1.ValidationError; } });
+Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_js_1.TimeoutError; } });
+var diesel_js_1 = require("./resources/diesel.js");
+Object.defineProperty(exports, "DieselResource", { enumerable: true, get: function () { return diesel_js_1.DieselResource; } });
+var alerts_js_1 = require("./resources/alerts.js");
+Object.defineProperty(exports, "AlertsResource", { enumerable: true, get: function () { return alerts_js_1.AlertsResource; } });
+var commodities_js_1 = require("./resources/commodities.js");
+Object.defineProperty(exports, "CommoditiesResource", { enumerable: true, get: function () { return commodities_js_1.CommoditiesResource; } });
+var futures_js_1 = require("./resources/futures.js");
+Object.defineProperty(exports, "FuturesResource", { enumerable: true, get: function () { return futures_js_1.FuturesResource; } });
+var storage_js_1 = require("./resources/storage.js");
+Object.defineProperty(exports, "StorageResource", { enumerable: true, get: function () { return storage_js_1.StorageResource; } });
+var rig_counts_js_1 = require("./resources/rig-counts.js");
+Object.defineProperty(exports, "RigCountsResource", { enumerable: true, get: function () { return rig_counts_js_1.RigCountsResource; } });
+var bunker_fuels_js_1 = require("./resources/bunker-fuels.js");
+Object.defineProperty(exports, "BunkerFuelsResource", { enumerable: true, get: function () { return bunker_fuels_js_1.BunkerFuelsResource; } });
+var analytics_js_1 = require("./resources/analytics.js");
+Object.defineProperty(exports, "AnalyticsResource", { enumerable: true, get: function () { return analytics_js_1.AnalyticsResource; } });
+var forecasts_js_1 = require("./resources/forecasts.js");
+Object.defineProperty(exports, "ForecastsResource", { enumerable: true, get: function () { return forecasts_js_1.ForecastsResource; } });
+var data_quality_js_1 = require("./resources/data-quality.js");
+Object.defineProperty(exports, "DataQualityResource", { enumerable: true, get: function () { return data_quality_js_1.DataQualityResource; } });
+var drilling_js_1 = require("./resources/drilling.js");
+Object.defineProperty(exports, "DrillingIntelligenceResource", { enumerable: true, get: function () { return drilling_js_1.DrillingIntelligenceResource; } });
+var index_js_1 = require("./resources/ei/index.js");
+Object.defineProperty(exports, "EnergyIntelligenceResource", { enumerable: true, get: function () { return index_js_1.EnergyIntelligenceResource; } });
+Object.defineProperty(exports, "EIRigCountsResource", { enumerable: true, get: function () { return index_js_1.EIRigCountsResource; } });
+Object.defineProperty(exports, "EIOilInventoriesResource", { enumerable: true, get: function () { return index_js_1.EIOilInventoriesResource; } });
+Object.defineProperty(exports, "EIOPECProductionResource", { enumerable: true, get: function () { return index_js_1.EIOPECProductionResource; } });
+Object.defineProperty(exports, "EIDrillingProductivityResource", { enumerable: true, get: function () { return index_js_1.EIDrillingProductivityResource; } });
+Object.defineProperty(exports, "EIForecastsResource", { enumerable: true, get: function () { return index_js_1.EIForecastsResource; } });
+Object.defineProperty(exports, "EIWellPermitsResource", { enumerable: true, get: function () { return index_js_1.EIWellPermitsResource; } });
+Object.defineProperty(exports, "EIFracFocusResource", { enumerable: true, get: function () { return index_js_1.EIFracFocusResource; } });
+var webhooks_js_1 = require("./resources/webhooks.js");
+Object.defineProperty(exports, "WebhooksResource", { enumerable: true, get: function () { return webhooks_js_1.WebhooksResource; } });
+var data_sources_js_1 = require("./resources/data-sources.js");
+Object.defineProperty(exports, "DataSourcesResource", { enumerable: true, get: function () { return data_sources_js_1.DataSourcesResource; } });
+/**
+ * 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);
+ * ```
+ */
+function verifyWebhookSignature(payload, signature, secret) {
+    const expectedSignature = "sha256=" + (0, node_crypto_1.createHmac)("sha256", secret).update(payload).digest("hex");
+    try {
+        return (0, node_crypto_1.timingSafeEqual)(Buffer.from(expectedSignature), Buffer.from(signature));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/resources/alerts.js

@@ -0,0 +1,387 @@
+"use strict";
+/**
+ * Price Alerts Resource
+ *
+ * Manage price alert configurations for automated notifications.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AlertsResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Price Alerts Resource
+ *
+ * Manage automated price alert configurations with webhook notifications.
+ *
+ * **Features:**
+ * - Create alerts with customizable conditions
+ * - Monitor commodity prices automatically
+ * - Webhook notifications when conditions are met
+ * - Cooldown periods to prevent spam
+ * - 100 alerts per user soft limit
+ *
+ * **Example:**
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Create a price alert
+ * const alert = await client.alerts.create({
+ *   name: 'Brent High Price Alert',
+ *   commodity_code: 'BRENT_CRUDE_USD',
+ *   condition_operator: 'greater_than',
+ *   condition_value: 85.00,
+ *   webhook_url: 'https://your-app.com/webhooks/price-alert',
+ *   enabled: true,
+ *   cooldown_minutes: 60
+ * });
+ *
+ * console.log(`Alert created: ${alert.name} (ID: ${alert.id})`);
+ *
+ * // List all alerts
+ * const alerts = await client.alerts.list();
+ * console.log(`You have ${alerts.length} active alerts`);
+ *
+ * // Update an alert
+ * const updated = await client.alerts.update(alert.id, {
+ *   condition_value: 90.00,
+ *   enabled: false
+ * });
+ *
+ * // Delete an alert
+ * await client.alerts.delete(alert.id);
+ * ```
+ */
+class AlertsResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all price alerts for the authenticated user
+     *
+     * Returns all configured price alerts, including disabled ones.
+     * Alerts are sorted by creation date (newest first).
+     *
+     * @returns Array of all price alerts
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     * @throws {RateLimitError} If rate limit exceeded
+     *
+     * @example
+     * ```typescript
+     * const alerts = await client.alerts.list();
+     *
+     * alerts.forEach(alert => {
+     *   console.log(`${alert.name}: ${alert.commodity_code} ${alert.condition_operator} ${alert.condition_value}`);
+     *   console.log(`  Status: ${alert.enabled ? 'Active' : 'Disabled'}`);
+     *   console.log(`  Triggers: ${alert.trigger_count}`);
+     * });
+     * ```
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/alerts", {});
+        // API returns array directly, but handle both formats for compatibility
+        return Array.isArray(response) ? response : response.alerts || [];
+    }
+    /**
+     * Get a specific price alert by ID
+     *
+     * @param id - The alert ID to retrieve
+     * @returns The price alert details
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {DataNotFoundError} If alert ID not found
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const alert = await client.alerts.get('550e8400-e29b-41d4-a716-446655440000');
+     * console.log(`Alert: ${alert.name}`);
+     * console.log(`Condition: ${alert.commodity_code} ${alert.condition_operator} ${alert.condition_value}`);
+     * console.log(`Last triggered: ${alert.last_triggered_at || 'Never'}`);
+     * ```
+     */
+    async get(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.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
+        return "alert" in response ? response.alert : response;
+    }
+    /**
+     * Create a new price alert
+     *
+     * Creates a price alert that monitors a commodity and triggers when
+     * the price meets the specified condition. Optionally sends webhook
+     * notifications when triggered.
+     *
+     * **Validation:**
+     * - name: 1-100 characters
+     * - commodity_code: Must be a valid commodity code
+     * - condition_value: Must be > 0 and <= 1,000,000
+     * - cooldown_minutes: Must be 0-1440 (24 hours)
+     * - webhook_url: Must be valid HTTPS URL if provided
+     *
+     * **Soft Limit:** 100 alerts per user
+     *
+     * @param params - Alert configuration parameters
+     * @returns The created price alert
+     *
+     * @throws {ValidationError} If parameters are invalid
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * // Alert when Brent crude exceeds $85
+     * const alert = await client.alerts.create({
+     *   name: 'Brent $85 Alert',
+     *   commodity_code: 'BRENT_CRUDE_USD',
+     *   condition_operator: 'greater_than',
+     *   condition_value: 85.00,
+     *   webhook_url: 'https://myapp.com/webhook',
+     *   enabled: true,
+     *   cooldown_minutes: 120  // 2 hours between triggers
+     * });
+     * ```
+     */
+    async create(params) {
+        // Validate required fields
+        if (!params.name || typeof params.name !== "string") {
+            throw new errors_js_1.ValidationError("Alert name is required and must be a string");
+        }
+        if (params.name.length < 1 || params.name.length > 100) {
+            throw new errors_js_1.ValidationError("Alert name must be 1-100 characters");
+        }
+        if (!params.commodity_code || typeof params.commodity_code !== "string") {
+            throw new errors_js_1.ValidationError("Commodity code is required and must be a string");
+        }
+        if (!params.condition_operator) {
+            throw new errors_js_1.ValidationError("Condition operator is required");
+        }
+        const validOperators = [
+            "greater_than",
+            "less_than",
+            "equals",
+            "greater_than_or_equal",
+            "less_than_or_equal",
+        ];
+        if (!validOperators.includes(params.condition_operator)) {
+            throw new errors_js_1.ValidationError(`Invalid operator. Must be one of: ${validOperators.join(", ")}`);
+        }
+        if (typeof params.condition_value !== "number") {
+            throw new errors_js_1.ValidationError("Condition value must be a number");
+        }
+        if (params.condition_value <= 0 || params.condition_value > 1000000) {
+            throw new errors_js_1.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 errors_js_1.ValidationError("Webhook URL must be a string");
+            }
+            if (params.webhook_url && !params.webhook_url.startsWith("https://")) {
+                throw new errors_js_1.ValidationError("Webhook URL must use HTTPS protocol");
+            }
+        }
+        if (params.cooldown_minutes !== undefined) {
+            if (typeof params.cooldown_minutes !== "number") {
+                throw new errors_js_1.ValidationError("Cooldown minutes must be a number");
+            }
+            if (params.cooldown_minutes < 0 || params.cooldown_minutes > 1440) {
+                throw new errors_js_1.ValidationError("Cooldown minutes must be between 0 and 1440 (24 hours)");
+            }
+        }
+        const response = await this.client["request"]("/v1/alerts", {}, {
+            method: "POST",
+            body: {
+                price_alert: {
+                    name: params.name,
+                    commodity_code: params.commodity_code,
+                    condition_operator: params.condition_operator,
+                    condition_value: params.condition_value,
+                    webhook_url: params.webhook_url,
+                    enabled: params.enabled ?? true,
+                    cooldown_minutes: params.cooldown_minutes ?? 60,
+                    metadata: params.metadata,
+                },
+            },
+        });
+        return "alert" in response ? response.alert : response;
+    }
+    /**
+     * Update an existing price alert
+     *
+     * Updates one or more fields of an existing alert. Only provided
+     * fields will be updated; others remain unchanged.
+     *
+     * @param id - The alert ID to update
+     * @param params - Fields to update (partial update supported)
+     * @returns The updated price alert
+     *
+     * @throws {ValidationError} If parameters are invalid
+     * @throws {DataNotFoundError} If alert ID not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * // Disable an alert
+     * await client.alerts.update(alertId, { enabled: false });
+     *
+     * // Change threshold and cooldown
+     * await client.alerts.update(alertId, {
+     *   condition_value: 90.00,
+     *   cooldown_minutes: 180
+     * });
+     *
+     * // Update webhook URL
+     * await client.alerts.update(alertId, {
+     *   webhook_url: 'https://newapp.com/webhook'
+     * });
+     * ```
+     */
+    async update(id, params) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.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 errors_js_1.ValidationError("Alert name must be 1-100 characters");
+            }
+        }
+        if (params.condition_operator !== undefined) {
+            const validOperators = [
+                "greater_than",
+                "less_than",
+                "equals",
+                "greater_than_or_equal",
+                "less_than_or_equal",
+            ];
+            if (!validOperators.includes(params.condition_operator)) {
+                throw new errors_js_1.ValidationError(`Invalid operator. Must be one of: ${validOperators.join(", ")}`);
+            }
+        }
+        if (params.condition_value !== undefined) {
+            if (typeof params.condition_value !== "number") {
+                throw new errors_js_1.ValidationError("Condition value must be a number");
+            }
+            if (params.condition_value <= 0 || params.condition_value > 1000000) {
+                throw new errors_js_1.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 errors_js_1.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 errors_js_1.ValidationError("Cooldown minutes must be between 0 and 1440 (24 hours)");
+            }
+        }
+        const response = await this.client["request"](`/v1/alerts/${id}`, {}, {
+            method: "PATCH",
+            body: { price_alert: params },
+        });
+        return "alert" in response ? response.alert : response;
+    }
+    /**
+     * Delete a price alert
+     *
+     * Permanently deletes a price alert. This action cannot be undone.
+     *
+     * @param id - The alert ID to delete
+     *
+     * @throws {DataNotFoundError} If alert ID not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * await client.alerts.delete(alertId);
+     * console.log('Alert deleted successfully');
+     * ```
+     */
+    async delete(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Alert ID must be a non-empty string");
+        }
+        await this.client["request"](`/v1/alerts/${id}`, {}, { method: "DELETE" });
+    }
+    /**
+     * Test an alert
+     *
+     * Triggers a test run of the alert to verify it's working correctly.
+     * Does not affect the alert's cooldown or trigger count.
+     *
+     * @param alertId - The alert ID to test
+     * @returns Test results
+     *
+     * @throws {NotFoundError} If alert not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.alerts.test(alertId);
+     * console.log(`Test ${result.success ? 'passed' : 'failed'}`);
+     * if (result.response_time_ms) {
+     *   console.log(`Webhook response time: ${result.response_time_ms}ms`);
+     * }
+     * ```
+     */
+    async test(alertId) {
+        if (!alertId || typeof alertId !== "string") {
+            throw new errors_js_1.ValidationError("Alert ID must be a non-empty string");
+        }
+        return this.client["request"](`/v1/alerts/${alertId}/test`, {}, { method: "POST" });
+    }
+    /**
+     * Get available alert triggers
+     *
+     * Returns list of supported trigger conditions and event types.
+     *
+     * @returns Array of available triggers
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const triggers = await client.alerts.triggers();
+     * triggers.forEach(trigger => {
+     *   console.log(`${trigger.name}: ${trigger.description}`);
+     * });
+     * ```
+     */
+    async triggers() {
+        const response = await this.client["request"]("/v1/alerts/triggers", {});
+        return Array.isArray(response) ? response : response.triggers;
+    }
+    /**
+     * Get alert analytics history
+     *
+     * Returns historical analytics data for alerts including trigger frequency,
+     * success rates, and response times.
+     *
+     * @returns Analytics history data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const analytics = await client.alerts.analyticsHistory();
+     * console.log(`Total triggers: ${analytics.total_triggers}`);
+     * console.log(`Success rate: ${analytics.success_rate}%`);
+     * ```
+     */
+    async analyticsHistory() {
+        return this.client["request"]("/v1/alerts/analytics_history", {});
+    }
+}
+exports.AlertsResource = AlertsResource;