oilpriceapi 0.6.0 → 0.8.2

package/dist/resources/diesel.js

@@ -1,3 +1,4 @@
+import { ValidationError } from "../errors.js";
 /**
  * Diesel Prices resource
  *
@@ -50,9 +51,9 @@ export class DieselResource {
      */
     async getPrice(state) {
         if (!state || state.length !== 2) {
-            throw new Error('State must be a 2-letter US state code (e.g., "CA", "TX")');
+            throw new ValidationError('State must be a 2-letter US state code (e.g., "CA", "TX")');
         }
-        const response = await this.client['request']('/v1/diesel-prices', { state: state.toUpperCase() });
+        const response = await this.client["request"]("/v1/diesel-prices", { state: state.toUpperCase() });
         return response.regional_average;
     }
     /**
@@ -98,47 +99,17 @@ export class DieselResource {
         const { lat, lng, radius = 8047 } = options;
         // Validate coordinates
         if (lat < -90 || lat > 90) {
-            throw new Error('Latitude must be between -90 and 90');
+            throw new ValidationError("Latitude must be between -90 and 90");
         }
         if (lng < -180 || lng > 180) {
-            throw new Error('Longitude must be between -180 and 180');
+            throw new ValidationError("Longitude must be between -180 and 180");
         }
         if (radius < 0 || radius > 50000) {
-            throw new Error('Radius must be between 0 and 50000 meters');
+            throw new ValidationError("Radius must be between 0 and 50000 meters");
         }
-        // Use POST request for stations endpoint
-        const response = await fetch(`${this.client['baseUrl']}/v1/diesel-prices/stations`, {
-            method: 'POST',
-            headers: {
-                'Authorization': `Bearer ${this.client['apiKey']}`,
-                'Content-Type': 'application/json',
-                'User-Agent': 'oilpriceapi-node/0.4.0',
-                'X-SDK-Language': 'javascript',
-                'X-SDK-Version': '0.4.0',
-                'X-Client-Type': 'sdk',
-            },
-            body: JSON.stringify({ lat, lng, radius }),
+        return this.client["request"]("/v1/diesel-prices/stations", {}, {
+            method: "POST",
+            body: { lat, lng, radius },
         });
-        if (!response.ok) {
-            const errorBody = await response.text();
-            let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
-            try {
-                const errorJson = JSON.parse(errorBody);
-                errorMessage = errorJson.message || errorJson.error || errorMessage;
-            }
-            catch {
-                // Use default error message
-            }
-            // Handle specific status codes
-            if (response.status === 403) {
-                throw new Error(`Diesel station queries not available on your plan. ${errorMessage}`);
-            }
-            if (response.status === 429) {
-                throw new Error(`Diesel station query limit exceeded. ${errorMessage}`);
-            }
-            throw new Error(errorMessage);
-        }
-        const data = await response.json();
-        return data;
     }
 }

package/dist/resources/drilling.d.ts

@@ -0,0 +1,403 @@
+/**
+ * Drilling Intelligence Resource
+ *
+ * Access US onshore drilling activity data including rig counts, well permits,
+ * frac spreads, DUC wells, completions, and production trends by basin.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Drilling intelligence data point
+ */
+export interface DrillingIntelligenceData {
+    /** Record ID */
+    id: string;
+    /** Basin name */
+    basin?: string;
+    /** State */
+    state?: string;
+    /** Operator name */
+    operator?: string;
+    /** Metric type */
+    metric_type: string;
+    /** Metric value */
+    value: number;
+    /** Unit of measurement */
+    unit?: string;
+    /** Report date */
+    date: string;
+    /** Week number */
+    week?: number;
+    /** ISO timestamp when data was recorded */
+    timestamp: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Latest drilling intelligence summary
+ */
+export interface LatestDrillingData {
+    /** Total active rigs */
+    total_rigs: number;
+    /** Total frac spreads */
+    total_frac_spreads: number;
+    /** Total well permits */
+    total_permits: number;
+    /** Total DUC wells */
+    total_duc_wells: number;
+    /** Total completions */
+    total_completions: number;
+    /** As of date */
+    as_of_date: string;
+    /** Additional metrics */
+    metrics?: Record<string, unknown>;
+}
+/**
+ * Drilling intelligence summary by metric
+ */
+export interface DrillingSummary {
+    /** Metric type */
+    metric: string;
+    /** Total count/value */
+    total: number;
+    /** Change from previous period */
+    change?: number;
+    /** Percentage change */
+    change_percent?: number;
+    /** Breakdown by basin or state */
+    breakdown?: Array<{
+        name: string;
+        value: number;
+        percentage?: number;
+    }>;
+}
+/**
+ * Drilling trend data
+ */
+export interface DrillingTrend {
+    /** Date */
+    date: string;
+    /** Metric type */
+    metric: string;
+    /** Value */
+    value: number;
+    /** Moving average (if applicable) */
+    moving_average?: number;
+    /** Trend direction */
+    trend?: "up" | "down" | "flat";
+}
+/**
+ * Frac spread data
+ */
+export interface FracSpreadData {
+    /** Basin name */
+    basin: string;
+    /** Number of active frac spreads */
+    active_spreads: number;
+    /** Change from previous week */
+    change?: number;
+    /** Date */
+    date: string;
+}
+/**
+ * Well permit data
+ */
+export interface WellPermitData {
+    /** State */
+    state: string;
+    /** Basin */
+    basin?: string;
+    /** Number of permits issued */
+    permits: number;
+    /** Change from previous period */
+    change?: number;
+    /** Date */
+    date: string;
+}
+/**
+ * DUC (Drilled but Uncompleted) well data
+ */
+export interface DUCWellData {
+    /** Basin name */
+    basin: string;
+    /** Number of DUC wells */
+    duc_count: number;
+    /** Change from previous month */
+    change?: number;
+    /** Date */
+    date: string;
+}
+/**
+ * Well completion data
+ */
+export interface CompletionData {
+    /** Basin name */
+    basin: string;
+    /** Number of completions */
+    completions: number;
+    /** Change from previous period */
+    change?: number;
+    /** Date */
+    date: string;
+}
+/**
+ * Wells drilled data
+ */
+export interface WellsDrilledData {
+    /** Basin name */
+    basin: string;
+    /** Number of wells drilled */
+    wells_drilled: number;
+    /** Change from previous period */
+    change?: number;
+    /** Date */
+    date: string;
+}
+/**
+ * Basin-specific drilling intelligence
+ */
+export interface BasinDrillingData {
+    /** Basin name */
+    basin: string;
+    /** Active rigs */
+    active_rigs?: number;
+    /** Frac spreads */
+    frac_spreads?: number;
+    /** Well permits */
+    permits?: number;
+    /** DUC wells */
+    duc_wells?: number;
+    /** Completions */
+    completions?: number;
+    /** Wells drilled */
+    wells_drilled?: number;
+    /** As of date */
+    as_of_date: string;
+    /** Historical trend */
+    trend?: DrillingTrend[];
+}
+/**
+ * Drilling Intelligence Resource
+ *
+ * Access US onshore drilling activity data from EIA and Baker Hughes.
+ * Includes rig counts, well permits, frac spreads, DUC wells, completions,
+ * and basin-level breakdowns.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest drilling intelligence
+ * const latest = await client.drilling.latest();
+ * console.log(`Active rigs: ${latest.total_rigs}`);
+ *
+ * // Get drilling trends
+ * const trends = await client.drilling.trends();
+ * trends.forEach(trend => {
+ *   console.log(`${trend.date}: ${trend.metric} = ${trend.value}`);
+ * });
+ *
+ * // Get basin-specific data
+ * const permian = await client.drilling.basin('Permian');
+ * console.log(`Permian rigs: ${permian.active_rigs}`);
+ * ```
+ */
+export declare class DrillingIntelligenceResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * List all drilling intelligence records
+     *
+     * Returns all available drilling intelligence data points.
+     *
+     * @returns Array of drilling intelligence data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const data = await client.drilling.list();
+     * console.log(`${data.length} records found`);
+     * ```
+     */
+    list(): Promise<DrillingIntelligenceData[]>;
+    /**
+     * Get latest drilling intelligence summary
+     *
+     * Returns the most recent snapshot of drilling activity metrics.
+     *
+     * @returns Latest drilling intelligence data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const latest = await client.drilling.latest();
+     * console.log(`Total active rigs: ${latest.total_rigs}`);
+     * console.log(`Frac spreads: ${latest.total_frac_spreads}`);
+     * console.log(`As of: ${latest.as_of_date}`);
+     * ```
+     */
+    latest(): Promise<LatestDrillingData>;
+    /**
+     * Get drilling intelligence summary
+     *
+     * Returns aggregated summary of drilling metrics by type.
+     *
+     * @returns Array of drilling summaries by metric
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const summary = await client.drilling.summary();
+     * summary.forEach(metric => {
+     *   console.log(`${metric.metric}: ${metric.total}`);
+     *   if (metric.change_percent) {
+     *     console.log(`  Change: ${metric.change_percent}%`);
+     *   }
+     * });
+     * ```
+     */
+    summary(): Promise<DrillingSummary[]>;
+    /**
+     * Get drilling activity trends
+     *
+     * Returns time series data showing trends in drilling metrics.
+     *
+     * @returns Array of drilling trend data points
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const trends = await client.drilling.trends();
+     * trends.forEach(point => {
+     *   console.log(`${point.date}: ${point.metric} = ${point.value} (${point.trend})`);
+     * });
+     * ```
+     */
+    trends(): Promise<DrillingTrend[]>;
+    /**
+     * Get frac spread data
+     *
+     * Returns active frac spread counts by basin.
+     *
+     * @returns Array of frac spread data by basin
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const fracSpreads = await client.drilling.fracSpreads();
+     * fracSpreads.forEach(spread => {
+     *   console.log(`${spread.basin}: ${spread.active_spreads} spreads`);
+     * });
+     * ```
+     */
+    fracSpreads(): Promise<FracSpreadData[]>;
+    /**
+     * Get well permit data
+     *
+     * Returns well permits issued by state and basin.
+     *
+     * @returns Array of well permit data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const permits = await client.drilling.wellPermits();
+     * permits.forEach(permit => {
+     *   console.log(`${permit.state}: ${permit.permits} permits`);
+     * });
+     * ```
+     */
+    wellPermits(): Promise<WellPermitData[]>;
+    /**
+     * Get DUC well data
+     *
+     * Returns drilled but uncompleted (DUC) well counts by basin.
+     *
+     * @returns Array of DUC well data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const ducWells = await client.drilling.ducWells();
+     * ducWells.forEach(duc => {
+     *   console.log(`${duc.basin}: ${duc.duc_count} DUC wells`);
+     * });
+     * ```
+     */
+    ducWells(): Promise<DUCWellData[]>;
+    /**
+     * Get well completion data
+     *
+     * Returns well completion counts by basin.
+     *
+     * @returns Array of completion data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const completions = await client.drilling.completions();
+     * completions.forEach(comp => {
+     *   console.log(`${comp.basin}: ${comp.completions} completions`);
+     * });
+     * ```
+     */
+    completions(): Promise<CompletionData[]>;
+    /**
+     * Get wells drilled data
+     *
+     * Returns wells drilled counts by basin.
+     *
+     * @returns Array of wells drilled data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const drilled = await client.drilling.wellsDrilled();
+     * drilled.forEach(data => {
+     *   console.log(`${data.basin}: ${data.wells_drilled} wells drilled`);
+     * });
+     * ```
+     */
+    wellsDrilled(): Promise<WellsDrilledData[]>;
+    /**
+     * Get basin-specific drilling intelligence
+     *
+     * Returns comprehensive drilling data for a specific basin.
+     *
+     * @param name - Basin name (e.g., "Permian", "Eagle Ford", "Bakken")
+     * @returns Basin drilling intelligence data
+     *
+     * @throws {NotFoundError} If basin not found
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const permian = await client.drilling.basin('Permian');
+     * console.log(`Permian Basin as of ${permian.as_of_date}:`);
+     * console.log(`  Active rigs: ${permian.active_rigs}`);
+     * console.log(`  Frac spreads: ${permian.frac_spreads}`);
+     * console.log(`  DUC wells: ${permian.duc_wells}`);
+     * ```
+     */
+    basin(name: string): Promise<BasinDrillingData>;
+}