oilpriceapi 0.6.0 → 0.8.2

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;

package/dist/cjs/resources/analytics.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Analytics Resource
+ *
+ * Access advanced analytics including performance metrics, statistical analysis,
+ * correlations, trend detection, spreads, and forecasts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnalyticsResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * 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}`);
+ * ```
+ */
+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 errors_js_1.ValidationError("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 errors_js_1.ValidationError("First commodity code must be a non-empty string");
+        }
+        if (!commodity2 || typeof commodity2 !== "string") {
+            throw new errors_js_1.ValidationError("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 errors_js_1.ValidationError("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 errors_js_1.ValidationError("First commodity code must be a non-empty string");
+        }
+        if (!commodity2 || typeof commodity2 !== "string") {
+            throw new errors_js_1.ValidationError("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 errors_js_1.ValidationError("Commodity code must be a non-empty string");
+        }
+        return this.client["request"]("/v1/analytics/forecast", {
+            commodity,
+        });
+    }
+}
+exports.AnalyticsResource = AnalyticsResource;