TypeScript Response Types

// oilpriceapi.d.ts

interface ApiResponse<T> {
  status: 'success' | 'error';
  data: T;
  meta?: ResponseMeta;
}

interface ResponseMeta {
  page?: number;
  per_page?: number;
  total_count?: number;
  total_pages?: number;
  api_version: string;
  cache_ttl?: number;
}

interface ApiError {
  status: 'error';
  error: {
    code: string;
    message: string;
    details?: Record<string, string[]>;
  };
}

interface Price {
  code: string;
  price: number;
  currency: string;
  unit: string;
  formatted: string;
  updated_at: string;
  change_24h?: number;
  change_24h_pct?: number;
}

interface LatestPriceResponse {
  status: 'success';
  data: Price | Price[];
}

interface HistoricalPrice {
  date: string;
  open: number;
  high: number;
  low: number;
  close: number;
  volume?: number;
}

interface HistoricalPriceResponse {
  status: 'success';
  data: {
    code: string;
    currency: string;
    unit: string;
    prices: HistoricalPrice[];
  };
}

interface FuturesContract {
  contract_month: string;  // Format: "YYYY-MM"
  last_price: number;
  currency: string;
  unit?: string;
  open: number;
  close: number;
  high: number;
  low: number;
  volume: number;
  change_percent: number;
  updated_at?: string;
}

interface FuturesResponse {
  commodity: string;
  source: 'ICE' | 'NYMEX';
  updated_at: string;
  trading_hours: string;
  contracts: FuturesContract[];
  metadata?: {
    total_contracts: number;
    data_source: string;
    retention_period: string;
  };
}

interface FuturesSpread {
  front_contract: string;
  back_contract: string;
  spread_type: string;
  current_spread: number;
  data_points: number;
  statistics: SpreadStatistics;
  daily_data?: SpreadDataPoint[];
}

interface SpreadStatistics {
  mean: number;
  median: number;
  min: number;
  max: number;
  standard_deviation: number;
  range: number;
}

interface SpreadDataPoint {
  trading_date: string;
  front_price: number;
  back_price: number;
  spread_value: number;
  spread_percentage: number;
}

interface FuturesCurve {
  analysis_date: string;
  curve_type: 'backwardation' | 'contango' | 'flat';
  total_contracts: number;
  front_month: CurveContract;
  back_month: CurveContract;
  contracts: CurveContract[];
  curve_metrics: CurveMetrics;
}

interface CurveContract {
  contract_month: string;
  settlement_price: number;
  months_to_expiry: number;
}

interface CurveMetrics {
  front_month_price: number;
  back_month_price: number;
  total_slope: number;
  slope_percentage: number;
  average_price: number;
  price_range: number;
  steepness: number;
}

interface RigCount {
  report_date: string;
  us_total: number;
  week_over_week: number;
  year_over_year: number;
  basins: Record<string, BasinRigCount>;
  top_states: StateRigCount[];
}

interface BasinRigCount {
  count: number;
  change: number;
}

interface StateRigCount {
  state: string;
  count: number;
  change: number;
}

interface OilInventory {
  week_ending: string;
  crude_commercial: InventoryLevel;
  gasoline: InventoryLevel;
  distillate: InventoryLevel;
  cushing: InventoryLevel;
}

interface InventoryLevel {
  volume_mmbbl: number;
  change_mmbbl: number;
  direction: 'build' | 'draw';
  utilization_pct?: number;
}

interface OPECProduction {
  report_month: string;
  opec_total_mbpd: number;
  month_over_month: number;
  headline: string;
  countries: OPECCountryProduction[];
}

interface OPECCountryProduction {
  country: string;
  name: string;
  production_mbpd: number;
  quota_mbpd?: number;
  compliance_pct?: number;
  spare_capacity_mbpd?: number;
  month_over_month: number;
}

interface DrillingProductivity {
  report_month: string;
  total_duc_wells: number;
  basins: BasinProductivity[];
}

interface BasinProductivity {
  basin: string;
  duc_wells: number;
  new_wells_per_rig: number;
  oil_productivity_bpd_per_rig: number | null;
  gas_productivity_mcf_per_rig: number | null;
}

interface STEOForecast {
  report_month: string;
  release_date: string;
  price_forecasts: {
    brent: PriceForecast;
    wti: PriceForecast;
    natural_gas: PriceForecast;
  };
  production_forecasts: {
    us_crude_mbpd: number;
    us_ngl_mbpd: number;
    opec_mbpd: number;
  };
}

interface PriceForecast {
  next_month: number;
  next_quarter_avg: number;
  next_year_avg: number;
}

interface StatisticsResponse {
  code: string;
  period: number;
  statistics: {
    z_score: number;
    z_score_interpretation: string;
    percentile: number;
    percentile_interpretation: string;
    volatility: number;
    volatility_interpretation: string;
  };
  tier: string;
}

interface CorrelationResponse {
  type: 'analysis' | 'matrix' | 'rolling';
  code1?: string;
  code2?: string;
  codes?: string[];
  period: number;
  correlation?: number;
  correlation_interpretation?: string;
  strength?: 'very_strong' | 'strong' | 'moderate' | 'weak' | 'none';
  direction?: 'positive' | 'negative';
  stability?: number;
  matrix?: Record<string, Record<string, number>>;
  rolling_correlation?: number[];
  tier: string;
}

interface TrendResponse {
  type: 'analysis' | 'sma' | 'ema' | 'rsi' | 'levels';
  code: string;
  period: number;
  trend?: {
    direction: 'bullish' | 'bearish' | 'neutral';
    strength: string;
    slope: number;
    price_change_pct: number;
  };
  momentum?: {
    rsi: number;
    interpretation: string;
  };
  moving_averages?: {
    sma_20: number;
    ema_20: number;
    price_vs_sma: 'above' | 'below';
    golden_cross: boolean;
  };
  levels?: {
    support: number[];
    resistance: number[];
    pivot_point: number;
  };
  signal?: {
    value: number;
    interpretation: string;
  };
  tier: string;
}

interface ForecastResponse {
  code: string;
  method: 'sma' | 'ema' | 'combined';
  current_price: number;
  data_points: number;
  volatility: number;
  forecasts: ForecastHorizon[];
  disclaimer: string;
  generated_at: string;
  tier: string;
}

interface ForecastHorizon {
  horizon_days: number;
  forecast_value: number;
  forecast_change_pct: number;
  confidence_intervals: {
    sigma_1: ConfidenceInterval;
    sigma_2: ConfidenceInterval;
  };
}

interface ConfidenceInterval {
  low: number;
  high: number;
  probability: number;
}

interface UserProfile {
  id: string;
  email: string;
  name: string;
  first_name: string;
  organization_name?: string;
  created_at: string;
  api_keys_count: number;
  subscription: Subscription;
}

interface Subscription {
  tier: string;
  status: 'active' | 'canceled' | 'past_due';
  monthly_limit: number;
  period_end: string;
}

interface UsageResponse {
  usage: {
    current_month: {
      used: number;
      limit: number;
      remaining: number;
      reset_at: string;
      percentage_used: number;
    };
    daily_breakdown: Record<string, number>;
    by_endpoint: EndpointUsage[];
    subscription_tier: string;
    organization?: string;
  };
}

interface EndpointUsage {
  endpoint: string;
  count: number;
}

interface ApiKey {
  id: string;
  token_preview: string;
  created_at: string;
  usage_this_month: number;
}

interface WebhookEvent {
  id: string;
  type: WebhookEventType;
  created_at: string;
  data: WebhookEventData;
}

type WebhookEventType =
  | 'price.updated'
  | 'price.alert'
  | 'drilling.report'
  | 'inventory.report'
  | 'api.limit_warning'
  | 'subscription.updated';

interface WebhookEventData {
  [key: string]: any;
}

import type {
  LatestPriceResponse,
  FuturesResponse,
  ApiError
} from './oilpriceapi';

async function getPrice(code: string): Promise<Price | null> {
  const response = await fetch(
    `https://api.oilpriceapi.com/v1/prices/latest?by_code=${code}`,
    { headers: { 'Authorization': `Token ${API_KEY}` } }
  );

  if (!response.ok) {
    const error: ApiError = await response.json();
    console.error(error.error.message);
    return null;
  }

  const data: LatestPriceResponse = await response.json();
  return data.data as Price;
}

async function getFutures(): Promise<FuturesContract[]> {
  const response = await fetch(
    'https://api.oilpriceapi.com/v1/futures/ice-brent',
    { headers: { 'Authorization': `Token ${API_KEY}` } }
  );

  const data: FuturesResponse = await response.json();
  return data.contracts;
}