oilpriceapi 0.8.2 → 0.9.0

package/dist/resources/analytics.d.ts

@@ -3,166 +3,152 @@
  *
  * Access advanced analytics including performance metrics, statistical analysis,
  * correlations, trend detection, spreads, and forecasts.
+ *
+ * NOTE ON PARAMETERS: The OilPriceAPI analytics controller reads commodity
+ * identifiers as `code` / `code1` / `code2` and the lookback window as `period`
+ * (in days). Earlier versions of this SDK sent `commodity` / `commodity1` /
+ * `commodity2` / `days`, which the API silently ignored (and `correlation`
+ * returned "code1 and code2 parameters are required"). These methods now send
+ * the parameter names the controller actually reads.
  */
 import type { OilPriceAPI } from "../client.js";
 /**
- * Performance metrics for commodities
+ * Performance metrics for the authenticated user's API usage.
+ *
+ * NOTE: `/v1/analytics/performance` returns the user's API usage analytics
+ * (request counts, error rate, endpoint breakdown) for a dashboard, NOT
+ * commodity price performance. It accepts a `range` of `7d` | `30d` | `90d`.
  */
 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;
+    overview?: Record<string, unknown>;
+    dailyUsage?: Array<Record<string, unknown>>;
+    hourlyDistribution?: Array<Record<string, unknown>>;
+    endpointBreakdown?: Array<Record<string, unknown>>;
+    geographicData?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
 }
 /**
  * Options for performance query
  */
 export interface PerformanceOptions {
-    /** Commodity code to analyze */
-    commodity?: string;
-    /** Number of days to analyze (default: 30) */
-    days?: number;
+    /** Time range for usage analytics: '7d' | '30d' | '90d' (default: '30d') */
+    range?: "7d" | "30d" | "90d";
 }
 /**
  * Statistical analysis results
  */
 export interface StatisticalAnalysis {
     /** Commodity code */
-    commodity: string;
+    code: 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;
+    period: number;
+    /** Statistical metrics computed for the commodity */
+    statistics: Record<string, unknown>;
+    /** Tier of the requesting user */
+    tier?: string;
+    [key: string]: unknown;
 }
 /**
  * Correlation analysis between two commodities
  */
 export interface CorrelationAnalysis {
+    /** Response type: 'analysis' | 'rolling' | 'matrix' */
+    type?: string;
     /** First commodity code */
-    commodity1: string;
+    code1?: string;
     /** Second commodity code */
-    commodity2: string;
+    code2?: string;
     /** Time period analyzed (in days) */
-    period_days: number;
+    period?: number;
     /** Pearson correlation coefficient (-1 to 1) */
-    correlation: number;
+    correlation?: number;
     /** Correlation strength description */
-    strength?: "strong" | "moderate" | "weak" | "none";
-    /** R-squared value */
-    r_squared?: number;
-    /** ISO timestamp */
-    timestamp: string;
+    strength?: string;
+    /** Tier of the requesting user */
+    tier?: string;
+    [key: string]: unknown;
+}
+/**
+ * Options for correlation query
+ */
+export interface CorrelationOptions {
+    /** Lookback window in days (default: 30) */
+    period?: number;
+    /** Correlation variant: 'analysis' (default), 'rolling', or 'matrix' */
+    type?: "analysis" | "rolling" | "matrix";
+    /** Rolling window size in days (only used when type === 'rolling') */
+    window?: number;
+    /** Comma-separated codes for a correlation matrix (only when type === 'matrix') */
+    codes?: string[];
 }
 /**
  * Trend analysis results
  */
 export interface TrendAnalysis {
+    /** Response type: 'analysis' | 'sma' | 'ema' | 'rsi' | 'levels' */
+    type?: string;
     /** Commodity code */
-    commodity: string;
+    code?: 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;
+    period?: number;
+    /** Tier of the requesting user */
+    tier?: string;
+    [key: string]: unknown;
+}
+/**
+ * Options for trend query
+ */
+export interface TrendOptions {
+    /** Lookback window in days (default: 30) */
+    period?: number;
+    /** Trend variant: 'analysis' (default), 'sma', 'ema', 'rsi', or 'levels' */
+    type?: "analysis" | "sma" | "ema" | "rsi" | "levels";
+    /** Moving-average / indicator window (used by sma/ema/rsi) */
+    window?: number;
 }
 /**
- * Spread analysis between commodities
+ * Spread analysis for a named commodity spread (e.g. 'wti_brent')
  */
 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;
+    /** Response type: 'current' | 'historical' */
+    type?: string;
+    /** The named spread analyzed */
+    spread?: string;
+    /** Time period analyzed (in days) */
+    period?: number;
+    /** Tier of the requesting user */
+    tier?: string;
+    [key: string]: unknown;
 }
 /**
- * Forecast data point
+ * Options for spread query
  */
-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;
+export interface SpreadOptions {
+    /** Lookback window in days (default: 30) */
+    period?: number;
+    /** Spread variant: 'current' (default) or 'historical' */
+    type?: "current" | "historical";
 }
 /**
  * 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;
+    code?: string;
+    /** Forecast method used */
+    method?: string;
+    /** Tier of the requesting user */
+    tier?: string;
+    [key: string]: unknown;
+}
+/**
+ * Options for forecast query
+ */
+export interface ForecastOptions {
+    /** Forecast method (default: 'ema') */
+    method?: string;
+    /** Lookback window in days (default: 90) */
+    period?: number;
 }
 /**
  * Analytics Resource
@@ -176,13 +162,8 @@ export interface PriceForecast {
  *
  * 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);
+ * // Analyze correlation between two commodities (90-day window)
+ * const corr = await client.analytics.correlation('WTI_USD', 'BRENT_CRUDE_USD', { period: 90 });
  * console.log(`Correlation: ${corr.correlation}`);
  * ```
  */
@@ -190,136 +171,88 @@ 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
+     * Get the authenticated user's API usage analytics for the dashboard.
      *
-     * @throws {OilPriceAPIError} If API request fails
+     * Maps to `GET /v1/analytics/performance`, which reads a `range`
+     * parameter (`7d` | `30d` | `90d`).
      *
-     * @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}`);
-     * ```
+     * @param options - `{ range }` (default range '30d')
+     * @returns Usage analytics (overview, daily usage, endpoint breakdown, ...)
      */
     performance(options?: PerformanceOptions): Promise<PerformanceMetrics>;
     /**
-     * Get statistical analysis for a commodity
+     * Get statistical analysis for a commodity.
      *
-     * Returns comprehensive statistical metrics including mean, median,
-     * standard deviation, and distribution characteristics.
+     * Maps to `GET /v1/analytics/statistics`, which reads `code` and `period`.
      *
-     * @param commodity - Commodity code to analyze
-     * @param days - Number of days to analyze (default: 30)
+     * @param code - Commodity code to analyze (e.g. 'WTI_USD')
+     * @param period - Lookback window in days (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}`);
-     * ```
+     * @throws {ValidationError} If code is empty
      */
-    statistics(commodity: string, days?: number): Promise<StatisticalAnalysis>;
+    statistics(code: string, period?: number): Promise<StatisticalAnalysis>;
     /**
-     * Analyze correlation between two commodities
+     * Analyze correlation between two commodities.
      *
-     * Calculates the Pearson correlation coefficient to measure how closely
-     * two commodities move together.
+     * Maps to `GET /v1/analytics/correlation`, which reads `code1`, `code2`,
+     * `period` and optional `type`, `window`, `codes`.
      *
-     * @param commodity1 - First commodity code
-     * @param commodity2 - Second commodity code
-     * @param days - Number of days to analyze (default: 30)
+     * @param code1 - First commodity code
+     * @param code2 - Second commodity code
+     * @param options - Lookback window in days, or `{ period, type, window, codes }`
      * @returns Correlation analysis
      *
-     * @throws {NotFoundError} If either commodity not found
-     * @throws {OilPriceAPIError} If API request fails
+     * @throws {ValidationError} If either code is empty
      *
      * @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}`);
+     * const corr = await client.analytics.correlation('WTI_USD', 'BRENT_CRUDE_USD', { period: 90 });
+     * console.log(corr.correlation);
      * ```
      */
-    correlation(commodity1: string, commodity2: string, days?: number): Promise<CorrelationAnalysis>;
+    correlation(code1: string, code2: string, options?: number | CorrelationOptions): Promise<CorrelationAnalysis>;
     /**
-     * Analyze price trend for a commodity
+     * Analyze price trend for a commodity.
      *
-     * Detects trend direction, strength, and key levels (support/resistance).
+     * Maps to `GET /v1/analytics/trend`, which reads `code`, `period` and
+     * optional `type` ('analysis' | 'sma' | 'ema' | 'rsi' | 'levels') and `window`.
      *
-     * @param commodity - Commodity code to analyze
-     * @param days - Number of days to analyze (default: 30)
+     * @param code - Commodity code to analyze
+     * @param options - Lookback window in days, or `{ period, type, window }`
      * @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}`);
-     * ```
+     * @throws {ValidationError} If code is empty
      */
-    trend(commodity: string, days?: number): Promise<TrendAnalysis>;
+    trend(code: string, options?: number | TrendOptions): Promise<TrendAnalysis>;
     /**
-     * Analyze spread between two commodities
-     *
-     * Calculates current spread and compares to historical patterns.
+     * Analyze a named commodity spread (basis / crack / ratio).
      *
-     * @param commodity1 - First commodity code
-     * @param commodity2 - Second commodity code
-     * @returns Spread analysis
+     * Maps to `GET /v1/analytics/spread`, which reads `spread` (the named spread,
+     * e.g. 'wti_brent'), `period` and optional `type` ('current' | 'historical').
+     * Call with no `spread` to list the available named spreads.
      *
-     * @throws {NotFoundError} If either commodity not found
-     * @throws {OilPriceAPIError} If API request fails
+     * @param spread - Named spread (e.g. 'wti_brent'); omit to list available spreads
+     * @param options - Lookback window in days, or `{ period, type }`
+     * @returns Spread analysis (or the list of available spreads)
      *
      * @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}`);
+     * const spread = await client.analytics.spread('wti_brent', { period: 30 });
+     * console.log(spread.current_spread);
      * ```
      */
-    spread(commodity1: string, commodity2: string): Promise<SpreadAnalysis>;
+    spread(spread?: string, options?: number | SpreadOptions): Promise<SpreadAnalysis>;
     /**
-     * Get price forecast for a commodity
-     *
-     * Returns forecasted prices with confidence intervals.
-     *
-     * @param commodity - Commodity code to forecast
-     * @returns Price forecast
+     * Get a statistical price forecast for a commodity.
      *
-     * @throws {NotFoundError} If commodity not found
-     * @throws {OilPriceAPIError} If API request fails
+     * Maps to `GET /v1/analytics/forecast`, which reads `code`, `method`
+     * (default 'ema') and `period` (default 90). Call with no `code` to list
+     * the available forecast methods.
      *
-     * @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})`);
-     * });
-     * ```
+     * @param code - Commodity code to forecast; omit to list available methods
+     * @param options - `{ method, period }`
+     * @returns Price forecast (or the list of available methods)
      */
-    forecast(commodity: string): Promise<PriceForecast>;
+    forecast(code?: string, options?: ForecastOptions): Promise<PriceForecast>;
 }