oilpriceapi 0.5.3 → 0.7.0

package/dist/resources/alerts.js

@@ -76,9 +76,9 @@ export class AlertsResource {
      * ```
      */
     async list() {
-        const response = await this.client['request']('/v1/alerts', {});
+        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 || []);
+        return Array.isArray(response) ? response : response.alerts || [];
     }
     /**
      * Get a specific price alert by ID
@@ -99,12 +99,12 @@ export class AlertsResource {
      * ```
      */
     async get(id) {
-        if (!id || typeof id !== 'string') {
-            throw new Error('Alert ID must be a non-empty string');
+        if (!id || typeof id !== "string") {
+            throw new Error("Alert ID must be a non-empty string");
         }
-        const response = await this.client['request'](`/v1/alerts/${id}`, {});
+        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;
+        return "alert" in response ? response.alert : response;
     }
     /**
      * Create a new price alert
@@ -145,57 +145,57 @@ 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');
+        if (!params.name || typeof params.name !== "string") {
+            throw new Error("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 Error("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');
+        if (!params.commodity_code || typeof params.commodity_code !== "string") {
+            throw new Error("Commodity code is required and must be a string");
         }
         if (!params.condition_operator) {
-            throw new Error('Condition operator is required');
+            throw new Error("Condition operator is required");
         }
         const validOperators = [
-            'greater_than',
-            'less_than',
-            'equals',
-            'greater_than_or_equal',
-            'less_than_or_equal'
+            "greater_than",
+            "less_than",
+            "equals",
+            "greater_than_or_equal",
+            "less_than_or_equal",
         ];
         if (!validOperators.includes(params.condition_operator)) {
-            throw new Error(`Invalid operator. Must be one of: ${validOperators.join(', ')}`);
+            throw new Error(`Invalid operator. Must be one of: ${validOperators.join(", ")}`);
         }
-        if (typeof params.condition_value !== 'number') {
-            throw new Error('Condition value must be a number');
+        if (typeof params.condition_value !== "number") {
+            throw new Error("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 Error("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');
+            if (typeof params.webhook_url !== "string") {
+                throw new Error("Webhook URL must be a string");
             }
-            if (params.webhook_url && !params.webhook_url.startsWith('https://')) {
-                throw new Error('Webhook URL must use HTTPS protocol');
+            if (params.webhook_url && !params.webhook_url.startsWith("https://")) {
+                throw new Error("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');
+            if (typeof params.cooldown_minutes !== "number") {
+                throw new Error("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 Error("Cooldown minutes must be between 0 and 1440 (24 hours)");
             }
         }
-        const url = `${this.client['baseUrl']}/v1/alerts`;
+        const url = `${this.client["baseUrl"]}/v1/alerts`;
         const response = await fetch(url, {
-            method: 'POST',
+            method: "POST",
             headers: {
-                'Authorization': `Bearer ${this.client['apiKey']}`,
-                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.client["apiKey"]}`,
+                "Content-Type": "application/json",
             },
             body: JSON.stringify({
                 price_alert: {
@@ -206,17 +206,17 @@ export class AlertsResource {
                     webhook_url: params.webhook_url,
                     enabled: params.enabled ?? true,
                     cooldown_minutes: params.cooldown_minutes ?? 60,
-                    metadata: params.metadata
-                }
-            })
+                    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();
+        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 data ? data.alert : data;
     }
     /**
      * Update an existing price alert
@@ -250,65 +250,68 @@ export class AlertsResource {
      * ```
      */
     async update(id, params) {
-        if (!id || typeof id !== 'string') {
-            throw new Error('Alert ID must be a non-empty string');
+        if (!id || typeof id !== "string") {
+            throw new Error("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');
+            if (typeof params.name !== "string" ||
+                params.name.length < 1 ||
+                params.name.length > 100) {
+                throw new Error("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'
+                "greater_than",
+                "less_than",
+                "equals",
+                "greater_than_or_equal",
+                "less_than_or_equal",
             ];
             if (!validOperators.includes(params.condition_operator)) {
-                throw new Error(`Invalid operator. Must be one of: ${validOperators.join(', ')}`);
+                throw new Error(`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');
+            if (typeof params.condition_value !== "number") {
+                throw new Error("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 Error("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');
+            if (typeof params.webhook_url !== "string" ||
+                !params.webhook_url.startsWith("https://")) {
+                throw new Error("Webhook URL must be a valid HTTPS URL");
             }
         }
         if (params.cooldown_minutes !== undefined) {
-            if (typeof params.cooldown_minutes !== 'number' ||
+            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 Error("Cooldown minutes must be between 0 and 1440 (24 hours)");
             }
         }
-        const url = `${this.client['baseUrl']}/v1/alerts/${id}`;
+        const url = `${this.client["baseUrl"]}/v1/alerts/${id}`;
         const response = await fetch(url, {
-            method: 'PATCH',
+            method: "PATCH",
             headers: {
-                'Authorization': `Bearer ${this.client['apiKey']}`,
-                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.client["apiKey"]}`,
+                "Content-Type": "application/json",
             },
             body: JSON.stringify({
-                price_alert: params
-            })
+                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();
+        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 data ? data.alert : data;
     }
     /**
      * Delete a price alert
@@ -327,16 +330,16 @@ export class AlertsResource {
      * ```
      */
     async delete(id) {
-        if (!id || typeof id !== 'string') {
-            throw new Error('Alert ID must be a non-empty string');
+        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 url = `${this.client["baseUrl"]}/v1/alerts/${id}`;
         const response = await fetch(url, {
-            method: 'DELETE',
+            method: "DELETE",
             headers: {
-                'Authorization': `Bearer ${this.client['apiKey']}`,
-                'Content-Type': 'application/json',
-            }
+                Authorization: `Bearer ${this.client["apiKey"]}`,
+                "Content-Type": "application/json",
+            },
         });
         if (!response.ok) {
             const errorText = await response.text();
@@ -344,28 +347,83 @@ export class AlertsResource {
         }
     }
     /**
-     * Test a webhook endpoint
+     * 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.
      *
-     * **NOTE:** This feature is not yet available in the API. The `/v1/alerts/test_webhook`
-     * endpoint has not been implemented yet. This method will throw an error until the
-     * backend endpoint is added.
+     * @param alertId - The alert ID to test
+     * @returns Test results
+     *
+     * @throws {NotFoundError} If alert not found
+     * @throws {OilPriceAPIError} If API request fails
      *
-     * To test if an alert would trigger, use the backend's `/v1/alerts/test` endpoint instead:
-     * ```bash
-     * curl -X POST "https://api.oilpriceapi.com/v1/alerts/:id/test" \
-     *   -H "Authorization: Bearer YOUR_API_KEY"
+     * @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 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}`);
+        }
+        return response.json();
+    }
+    /**
+     * Get available alert triggers
      *
-     * @param webhookUrl - The HTTPS webhook URL to test
-     * @returns Test results including response time and status
+     * Returns list of supported trigger conditions and event types.
      *
-     * @throws {Error} Feature not yet available
+     * @returns Array of available triggers
      *
-     * @deprecated This feature is not yet available in the API
+     * @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 testWebhook(webhookUrl) {
-        throw new Error('Webhook testing is not yet available. The /v1/alerts/test_webhook endpoint ' +
-            'has not been implemented in the API. To test if an alert would trigger, ' +
-            'use the /v1/alerts/:id/test endpoint instead.');
+    async analyticsHistory() {
+        return this.client["request"]("/v1/alerts/analytics_history", {});
     }
 }

package/dist/resources/analytics.d.ts

@@ -0,0 +1,325 @@
+/**
+ * Analytics Resource
+ *
+ * Access advanced analytics including performance metrics, statistical analysis,
+ * correlations, trend detection, spreads, and forecasts.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Performance metrics for commodities
+ */
+export interface PerformanceMetrics {
+    /** Commodity code */
+    commodity?: string;
+    /** Time period analyzed (in days) */
+    period_days: number;
+    /** Average price over period */
+    average_price: number;
+    /** Price volatility (standard deviation) */
+    volatility: number;
+    /** Percentage return over period */
+    return_percent: number;
+    /** Highest price in period */
+    high: number;
+    /** Lowest price in period */
+    low: number;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Options for performance query
+ */
+export interface PerformanceOptions {
+    /** Commodity code to analyze */
+    commodity?: string;
+    /** Number of days to analyze (default: 30) */
+    days?: number;
+}
+/**
+ * Statistical analysis results
+ */
+export interface StatisticalAnalysis {
+    /** Commodity code */
+    commodity: string;
+    /** Time period analyzed (in days) */
+    period_days: number;
+    /** Mean price */
+    mean: number;
+    /** Median price */
+    median: number;
+    /** Standard deviation */
+    std_dev: number;
+    /** Variance */
+    variance: number;
+    /** Minimum price */
+    min: number;
+    /** Maximum price */
+    max: number;
+    /** 25th percentile */
+    percentile_25?: number;
+    /** 75th percentile */
+    percentile_75?: number;
+    /** Skewness */
+    skewness?: number;
+    /** Kurtosis */
+    kurtosis?: number;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Correlation analysis between two commodities
+ */
+export interface CorrelationAnalysis {
+    /** First commodity code */
+    commodity1: string;
+    /** Second commodity code */
+    commodity2: string;
+    /** Time period analyzed (in days) */
+    period_days: number;
+    /** Pearson correlation coefficient (-1 to 1) */
+    correlation: number;
+    /** Correlation strength description */
+    strength?: "strong" | "moderate" | "weak" | "none";
+    /** R-squared value */
+    r_squared?: number;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Trend analysis results
+ */
+export interface TrendAnalysis {
+    /** Commodity code */
+    commodity: string;
+    /** Time period analyzed (in days) */
+    period_days: number;
+    /** Overall trend direction */
+    trend: "upward" | "downward" | "sideways";
+    /** Trend strength (0-100) */
+    strength: number;
+    /** Slope of trend line */
+    slope?: number;
+    /** Price momentum */
+    momentum?: number;
+    /** Support level */
+    support?: number;
+    /** Resistance level */
+    resistance?: number;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Spread analysis between commodities
+ */
+export interface SpreadAnalysis {
+    /** First commodity code */
+    commodity1: string;
+    /** Second commodity code */
+    commodity2: string;
+    /** Current spread (commodity1 - commodity2) */
+    spread: number;
+    /** Historical average spread */
+    average_spread?: number;
+    /** Spread standard deviation */
+    spread_volatility?: number;
+    /** Z-score of current spread */
+    z_score?: number;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Forecast data point
+ */
+export interface ForecastPoint {
+    /** Forecast date */
+    date: string;
+    /** Forecasted price */
+    price: number;
+    /** Lower bound of confidence interval */
+    lower_bound?: number;
+    /** Upper bound of confidence interval */
+    upper_bound?: number;
+    /** Confidence level (e.g., 0.95 for 95%) */
+    confidence?: number;
+}
+/**
+ * Price forecast
+ */
+export interface PriceForecast {
+    /** Commodity code */
+    commodity: string;
+    /** Forecast model used */
+    model?: string;
+    /** Forecast horizon (days ahead) */
+    horizon_days: number;
+    /** Array of forecast points */
+    forecast: ForecastPoint[];
+    /** Model accuracy metrics */
+    accuracy?: {
+        /** Mean Absolute Percentage Error */
+        mape?: number;
+        /** Root Mean Squared Error */
+        rmse?: number;
+    };
+    /** ISO timestamp when forecast was generated */
+    timestamp: string;
+}
+/**
+ * Analytics Resource
+ *
+ * Access advanced analytics including performance metrics, statistical analysis,
+ * correlations, trends, spreads, and forecasts.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get performance metrics
+ * const perf = await client.analytics.performance({ commodity: 'WTI_USD', days: 30 });
+ * console.log(`30-day return: ${perf.return_percent}%`);
+ * console.log(`Volatility: ${perf.volatility}`);
+ *
+ * // Analyze correlation
+ * const corr = await client.analytics.correlation('WTI_USD', 'BRENT_CRUDE_USD', 90);
+ * console.log(`Correlation: ${corr.correlation}`);
+ * ```
+ */
+export declare class AnalyticsResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * 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}`);
+     * ```
+     */
+    performance(options?: PerformanceOptions): Promise<PerformanceMetrics>;
+    /**
+     * 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}`);
+     * ```
+     */
+    statistics(commodity: string, days?: number): Promise<StatisticalAnalysis>;
+    /**
+     * 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}`);
+     * ```
+     */
+    correlation(commodity1: string, commodity2: string, days?: number): Promise<CorrelationAnalysis>;
+    /**
+     * 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}`);
+     * ```
+     */
+    trend(commodity: string, days?: number): Promise<TrendAnalysis>;
+    /**
+     * 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}`);
+     * ```
+     */
+    spread(commodity1: string, commodity2: string): Promise<SpreadAnalysis>;
+    /**
+     * 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})`);
+     * });
+     * ```
+     */
+    forecast(commodity: string): Promise<PriceForecast>;
+}