oilpriceapi 0.6.0 → 0.8.2

package/dist/resources/drilling.js

@@ -0,0 +1,265 @@
+/**
+ * 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 { ValidationError } from "../errors.js";
+/**
+ * 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 class DrillingIntelligenceResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * 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`);
+     * ```
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/drilling-intelligence", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * 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}`);
+     * ```
+     */
+    async latest() {
+        return this.client["request"]("/v1/drilling-intelligence/latest", {});
+    }
+    /**
+     * 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}%`);
+     *   }
+     * });
+     * ```
+     */
+    async summary() {
+        const response = await this.client["request"]("/v1/drilling-intelligence/summary", {});
+        return Array.isArray(response) ? response : response.summary;
+    }
+    /**
+     * 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})`);
+     * });
+     * ```
+     */
+    async trends() {
+        const response = await this.client["request"]("/v1/drilling-intelligence/trends", {});
+        return Array.isArray(response) ? response : response.trends;
+    }
+    /**
+     * 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`);
+     * });
+     * ```
+     */
+    async fracSpreads() {
+        const response = await this.client["request"]("/v1/drilling-intelligence/frac-spreads", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * 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`);
+     * });
+     * ```
+     */
+    async wellPermits() {
+        const response = await this.client["request"]("/v1/drilling-intelligence/well-permits", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * 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`);
+     * });
+     * ```
+     */
+    async ducWells() {
+        const response = await this.client["request"]("/v1/drilling-intelligence/duc-wells", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * 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`);
+     * });
+     * ```
+     */
+    async completions() {
+        const response = await this.client["request"]("/v1/drilling-intelligence/completions", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * 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`);
+     * });
+     * ```
+     */
+    async wellsDrilled() {
+        const response = await this.client["request"]("/v1/drilling-intelligence/wells-drilled", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * 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}`);
+     * ```
+     */
+    async basin(name) {
+        if (!name || typeof name !== "string") {
+            throw new ValidationError("Basin name must be a non-empty string");
+        }
+        return this.client["request"](`/v1/drilling-intelligence/basin/${name}`, {});
+    }
+}

package/dist/resources/ei/drilling-productivity.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Energy Intelligence - Drilling Productivity Resource
+ *
+ * Access EIA Drilling Productivity Report data including new well production,
+ * legacy decline rates, and DUC well inventories by basin.
+ */
+import type { OilPriceAPI } from "../../client.js";
+/**
+ * Drilling productivity record
+ */
+export interface DrillingProductivityRecord {
+    /** Record ID */
+    id: string;
+    /** Basin name */
+    basin?: string;
+    /** New well oil production per rig (barrels/day) */
+    new_well_oil_production?: number;
+    /** New well gas production per rig (mcf/day) */
+    new_well_gas_production?: number;
+    /** Legacy production change (oil) */
+    legacy_oil_change?: number;
+    /** Legacy production change (gas) */
+    legacy_gas_change?: number;
+    /** DUC well count */
+    duc_count?: number;
+    /** Report date */
+    date: string;
+    /** Month */
+    month?: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Drilling productivity summary
+ */
+export interface DrillingProductivitySummary {
+    /** Total new well oil production */
+    total_new_well_oil?: number;
+    /** Total new well gas production */
+    total_new_well_gas?: number;
+    /** Total DUC wells */
+    total_duc_wells?: number;
+    /** As of date */
+    as_of_date: string;
+}
+/**
+ * DUC well data
+ */
+export interface DUCWellInventory {
+    /** Basin name */
+    basin: string;
+    /** DUC well count */
+    duc_count: number;
+    /** Change from previous month */
+    change?: number;
+    /** Date */
+    date: string;
+}
+/**
+ * Productivity by basin
+ */
+export interface ProductivityByBasin {
+    /** Basin name */
+    basin: string;
+    /** New well oil production */
+    new_well_oil_production?: number;
+    /** New well gas production */
+    new_well_gas_production?: number;
+    /** DUC count */
+    duc_count?: number;
+    /** Date */
+    date: string;
+}
+/**
+ * Historical productivity data point
+ */
+export interface HistoricalProductivity {
+    /** Date */
+    date: string;
+    /** New well oil production */
+    new_well_oil_production?: number;
+    /** New well gas production */
+    new_well_gas_production?: number;
+    /** DUC count */
+    duc_count?: number;
+}
+/**
+ * Productivity trend data
+ */
+export interface ProductivityTrend {
+    /** Basin name */
+    basin: string;
+    /** Trend direction */
+    trend: "up" | "down" | "flat";
+    /** Change percentage */
+    change_percent?: number;
+    /** Metric type */
+    metric: string;
+}
+/**
+ * EI Drilling Productivity Resource
+ *
+ * Access EIA Drilling Productivity Report data for major US basins.
+ *
+ * @example
+ * ```typescript
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest productivity data
+ * const latest = await client.ei.drillingProductivity.latest();
+ * console.log(`Basin: ${latest.basin}`);
+ * console.log(`New well oil: ${latest.new_well_oil_production} bpd/rig`);
+ *
+ * // Get DUC wells
+ * const duc = await client.ei.drillingProductivity.ducWells();
+ * duc.forEach(d => console.log(`${d.basin}: ${d.duc_count} DUC wells`));
+ * ```
+ */
+export declare class EIDrillingProductivityResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * List all drilling productivity records
+     *
+     * @returns Array of productivity records
+     */
+    list(): Promise<DrillingProductivityRecord[]>;
+    /**
+     * Get a specific productivity record
+     *
+     * @param id - Record ID
+     * @returns Productivity record
+     */
+    get(id: string): Promise<DrillingProductivityRecord>;
+    /**
+     * Get latest drilling productivity data
+     *
+     * @returns Latest productivity record
+     */
+    latest(): Promise<DrillingProductivityRecord>;
+    /**
+     * Get drilling productivity summary
+     *
+     * @returns Productivity summary across all basins
+     */
+    summary(): Promise<DrillingProductivitySummary>;
+    /**
+     * Get DUC well inventories
+     *
+     * @returns Array of DUC well counts by basin
+     */
+    ducWells(): Promise<DUCWellInventory[]>;
+    /**
+     * Get productivity by basin
+     *
+     * @returns Array of productivity data by basin
+     */
+    byBasin(): Promise<ProductivityByBasin[]>;
+    /**
+     * Get historical productivity data
+     *
+     * @returns Array of historical productivity metrics
+     */
+    historical(): Promise<HistoricalProductivity[]>;
+    /**
+     * Get productivity trends
+     *
+     * @returns Array of productivity trends by basin
+     */
+    trends(): Promise<ProductivityTrend[]>;
+}

package/dist/resources/ei/drilling-productivity.js

@@ -0,0 +1,104 @@
+/**
+ * Energy Intelligence - Drilling Productivity Resource
+ *
+ * Access EIA Drilling Productivity Report data including new well production,
+ * legacy decline rates, and DUC well inventories by basin.
+ */
+import { ValidationError } from "../../errors.js";
+/**
+ * EI Drilling Productivity Resource
+ *
+ * Access EIA Drilling Productivity Report data for major US basins.
+ *
+ * @example
+ * ```typescript
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get latest productivity data
+ * const latest = await client.ei.drillingProductivity.latest();
+ * console.log(`Basin: ${latest.basin}`);
+ * console.log(`New well oil: ${latest.new_well_oil_production} bpd/rig`);
+ *
+ * // Get DUC wells
+ * const duc = await client.ei.drillingProductivity.ducWells();
+ * duc.forEach(d => console.log(`${d.basin}: ${d.duc_count} DUC wells`));
+ * ```
+ */
+export class EIDrillingProductivityResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all drilling productivity records
+     *
+     * @returns Array of productivity records
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/ei/drilling_productivities", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get a specific productivity record
+     *
+     * @param id - Record ID
+     * @returns Productivity record
+     */
+    async get(id) {
+        if (!id || typeof id !== "string") {
+            throw new ValidationError("Record ID must be a non-empty string");
+        }
+        return this.client["request"](`/v1/ei/drilling_productivities/${id}`, {});
+    }
+    /**
+     * Get latest drilling productivity data
+     *
+     * @returns Latest productivity record
+     */
+    async latest() {
+        return this.client["request"]("/v1/ei/drilling_productivities/latest", {});
+    }
+    /**
+     * Get drilling productivity summary
+     *
+     * @returns Productivity summary across all basins
+     */
+    async summary() {
+        return this.client["request"]("/v1/ei/drilling_productivities/summary", {});
+    }
+    /**
+     * Get DUC well inventories
+     *
+     * @returns Array of DUC well counts by basin
+     */
+    async ducWells() {
+        const response = await this.client["request"]("/v1/ei/drilling_productivities/duc_wells", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get productivity by basin
+     *
+     * @returns Array of productivity data by basin
+     */
+    async byBasin() {
+        const response = await this.client["request"]("/v1/ei/drilling_productivities/by_basin", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get historical productivity data
+     *
+     * @returns Array of historical productivity metrics
+     */
+    async historical() {
+        const response = await this.client["request"]("/v1/ei/drilling_productivities/historical", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get productivity trends
+     *
+     * @returns Array of productivity trends by basin
+     */
+    async trends() {
+        const response = await this.client["request"]("/v1/ei/drilling_productivities/trends", {});
+        return Array.isArray(response) ? response : response.data;
+    }
+}