oilpriceapi 0.7.0 → 0.8.2

package/dist/cjs/resources/data-sources.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * Data Sources Resource
+ *
+ * Manage custom data source integrations for Bring Your Own Source (BYOS) feature.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataSourcesResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Data Sources Resource
+ *
+ * Manage custom data source integrations for importing your own price data
+ * into the platform (BYOS - Bring Your Own Source feature).
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Create a data source
+ * const source = await client.dataSources.create({
+ *   name: 'Internal Price Feed',
+ *   type: 'api',
+ *   config: {
+ *     url: 'https://internal.company.com/api/prices',
+ *     auth_type: 'bearer',
+ *     token: 'secret-token'
+ *   },
+ *   sync_frequency_minutes: 30
+ * });
+ *
+ * // Test the data source
+ * const test = await client.dataSources.test(source.id);
+ * console.log(`Test result: ${test.success}`);
+ *
+ * // Check health
+ * const health = await client.dataSources.health(source.id);
+ * console.log(`Health: ${health.status}`);
+ * console.log(`Success rate: ${health.success_rate}%`);
+ *
+ * // View sync logs
+ * const logs = await client.dataSources.logs(source.id);
+ * logs.forEach(log => {
+ *   console.log(`${log.started_at}: ${log.status} - ${log.records_synced} records`);
+ * });
+ * ```
+ */
+class DataSourcesResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all data sources
+     *
+     * @returns Array of data sources
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const sources = await client.dataSources.list();
+     * sources.forEach(source => {
+     *   console.log(`${source.name}: ${source.status}`);
+     *   console.log(`  Success rate: ${source.successful_syncs}/${source.successful_syncs + source.failed_syncs}`);
+     * });
+     * ```
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/data-sources", {});
+        return Array.isArray(response) ? response : response.data_sources;
+    }
+    /**
+     * Get a specific data source
+     *
+     * @param id - Data source ID
+     * @returns Data source details
+     *
+     * @throws {NotFoundError} If data source not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const source = await client.dataSources.get('source-id');
+     * console.log(`${source.name} (${source.type})`);
+     * console.log(`Last sync: ${source.last_sync_at}`);
+     * ```
+     */
+    async get(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Data source ID must be a non-empty string");
+        }
+        const response = await this.client["request"](`/v1/data-sources/${id}`, {});
+        return "data_source" in response ? response.data_source : response;
+    }
+    /**
+     * Create a new data source
+     *
+     * @param params - Data source configuration
+     * @returns Created data source
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const source = await client.dataSources.create({
+     *   name: 'SFTP Price Feed',
+     *   type: 'sftp',
+     *   config: {
+     *     host: 'sftp.example.com',
+     *     username: 'user',
+     *     password: 'pass',
+     *     path: '/prices/daily.csv'
+     *   },
+     *   sync_frequency_minutes: 1440 // Daily
+     * });
+     * ```
+     */
+    async create(params) {
+        if (!params.name || typeof params.name !== "string") {
+            throw new errors_js_1.ValidationError("Data source name is required");
+        }
+        if (!params.type) {
+            throw new errors_js_1.ValidationError("Data source type is required");
+        }
+        if (!params.config || typeof params.config !== "object") {
+            throw new errors_js_1.ValidationError("Data source config is required");
+        }
+        const response = await this.client["request"]("/v1/data-sources", {}, {
+            method: "POST",
+            body: {
+                data_source: {
+                    name: params.name,
+                    type: params.type,
+                    config: params.config,
+                    enabled: params.enabled ?? true,
+                    sync_frequency_minutes: params.sync_frequency_minutes ?? 60,
+                    metadata: params.metadata,
+                },
+            },
+        });
+        return "data_source" in response ? response.data_source : response;
+    }
+    /**
+     * Update a data source
+     *
+     * @param id - Data source ID
+     * @param params - Fields to update
+     * @returns Updated data source
+     *
+     * @throws {NotFoundError} If data source not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * // Pause a data source
+     * await client.dataSources.update(sourceId, { enabled: false });
+     *
+     * // Update sync frequency
+     * await client.dataSources.update(sourceId, {
+     *   sync_frequency_minutes: 120
+     * });
+     * ```
+     */
+    async update(id, params) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Data source ID must be a non-empty string");
+        }
+        const response = await this.client["request"](`/v1/data-sources/${id}`, {}, {
+            method: "PATCH",
+            body: { data_source: params },
+        });
+        return "data_source" in response ? response.data_source : response;
+    }
+    /**
+     * Delete a data source
+     *
+     * @param id - Data source ID
+     *
+     * @throws {NotFoundError} If data source not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * await client.dataSources.delete(sourceId);
+     * console.log('Data source deleted');
+     * ```
+     */
+    async delete(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Data source ID must be a non-empty string");
+        }
+        await this.client["request"](`/v1/data-sources/${id}`, {}, { method: "DELETE" });
+    }
+    /**
+     * Test a data source connection
+     *
+     * @param id - Data source ID
+     * @returns Test results
+     *
+     * @throws {NotFoundError} If data source not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const test = await client.dataSources.test(sourceId);
+     * console.log(`Connection test: ${test.success ? 'passed' : 'failed'}`);
+     * console.log(`Duration: ${test.duration_ms}ms`);
+     * if (test.sample_data) {
+     *   console.log(`Sample records: ${test.sample_data.length}`);
+     * }
+     * ```
+     */
+    async test(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Data source ID must be a non-empty string");
+        }
+        return this.client["request"](`/v1/data-sources/${id}/test`, {}, { method: "POST" });
+    }
+    /**
+     * Get data source sync logs
+     *
+     * @param id - Data source ID
+     * @returns Array of sync log entries
+     *
+     * @throws {NotFoundError} If data source not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const logs = await client.dataSources.logs(sourceId);
+     * logs.forEach(log => {
+     *   console.log(`${log.started_at}: ${log.status}`);
+     *   if (log.records_synced) {
+     *     console.log(`  ${log.records_synced} records in ${log.duration_ms}ms`);
+     *   }
+     * });
+     * ```
+     */
+    async logs(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Data source ID must be a non-empty string");
+        }
+        const response = await this.client["request"](`/v1/data-sources/${id}/logs`, {});
+        return Array.isArray(response) ? response : response.logs;
+    }
+    /**
+     * Get data source health metrics
+     *
+     * @param id - Data source ID
+     * @returns Health metrics
+     *
+     * @throws {NotFoundError} If data source not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const health = await client.dataSources.health(sourceId);
+     * console.log(`Status: ${health.status}`);
+     * console.log(`Success rate: ${health.success_rate}%`);
+     * console.log(`Avg duration: ${health.avg_duration_ms}ms`);
+     * ```
+     */
+    async health(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Data source ID must be a non-empty string");
+        }
+        return this.client["request"](`/v1/data-sources/${id}/health`, {});
+    }
+    /**
+     * Rotate data source credentials
+     *
+     * Updates stored credentials with new values and re-encrypts them.
+     *
+     * @param id - Data source ID
+     * @returns Rotation result
+     *
+     * @throws {NotFoundError} If data source not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.dataSources.rotateCredentials(sourceId);
+     * console.log(`Credential rotation: ${result.success ? 'success' : 'failed'}`);
+     * ```
+     */
+    async rotateCredentials(id) {
+        if (!id || typeof id !== "string") {
+            throw new errors_js_1.ValidationError("Data source ID must be a non-empty string");
+        }
+        return this.client["request"](`/v1/data-sources/${id}/rotate-credentials`, {}, { method: "POST" });
+    }
+}
+exports.DataSourcesResource = DataSourcesResource;

package/dist/cjs/resources/diesel.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DieselResource = void 0;
+const errors_js_1 = require("../errors.js");
+/**
+ * Diesel Prices resource
+ *
+ * Provides access to state-level diesel averages and station-level pricing.
+ *
+ * @example
+ * ```typescript
+ * // Get state average
+ * const caPrice = await client.diesel.getPrice('CA');
+ * console.log(`California diesel: $${caPrice.price}/gal`);
+ *
+ * // Get nearby stations
+ * const stations = await client.diesel.getStations({
+ *   lat: 37.7749,
+ *   lng: -122.4194,
+ *   radius: 8047  // 5 miles in meters
+ * });
+ *
+ * console.log(`Found ${stations.stations.length} stations`);
+ * stations.stations.forEach(station => {
+ *   console.log(`${station.name}: ${station.formatted_price}`);
+ * });
+ * ```
+ */
+class DieselResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get average diesel price for a US state
+     *
+     * Returns EIA state-level average diesel price. This endpoint is free
+     * and included in all tiers.
+     *
+     * @param state - Two-letter US state code (e.g., "CA", "TX", "NY")
+     * @returns State average diesel price
+     *
+     * @throws {NotFoundError} If state code is invalid
+     * @throws {AuthenticationError} If API key is invalid
+     * @throws {RateLimitError} If rate limit exceeded
+     *
+     * @example
+     * ```typescript
+     * // Get California diesel price
+     * const caPrice = await client.diesel.getPrice('CA');
+     * console.log(`CA diesel: $${caPrice.price}/gal`);
+     * console.log(`Source: ${caPrice.source}`);
+     * console.log(`Updated: ${caPrice.updated_at}`);
+     * ```
+     */
+    async getPrice(state) {
+        if (!state || state.length !== 2) {
+            throw new errors_js_1.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() });
+        return response.regional_average;
+    }
+    /**
+     * Get nearby diesel stations with current pricing
+     *
+     * Returns station-level diesel prices within specified radius using Google Maps data.
+     *
+     * **Pricing:** Included in paid tiers:
+     * - Exploration: 100 station queries/month
+     * - Starter: 500 station queries/month
+     * - Professional: 2,000 station queries/month
+     * - Business: 5,000 station queries/month
+     *
+     * **Caching:** Results are cached for 24 hours to minimize costs.
+     *
+     * @param options - Search parameters (lat, lng, radius)
+     * @returns Nearby stations with prices and regional average
+     *
+     * @throws {AuthenticationError} If API key is invalid
+     * @throws {RateLimitError} If monthly station query limit exceeded
+     * @throws {Error} If coordinates are invalid
+     *
+     * @example
+     * ```typescript
+     * // Get stations near San Francisco
+     * const result = await client.diesel.getStations({
+     *   lat: 37.7749,
+     *   lng: -122.4194,
+     *   radius: 8047  // 5 miles
+     * });
+     *
+     * console.log(`Regional avg: $${result.regional_average.price}/gal`);
+     * console.log(`Found ${result.stations.length} stations`);
+     *
+     * // Find cheapest station
+     * const cheapest = result.stations.reduce((min, s) =>
+     *   s.diesel_price < min.diesel_price ? s : min
+     * );
+     * console.log(`Cheapest: ${cheapest.name} at ${cheapest.formatted_price}`);
+     * ```
+     */
+    async getStations(options) {
+        const { lat, lng, radius = 8047 } = options;
+        // Validate coordinates
+        if (lat < -90 || lat > 90) {
+            throw new errors_js_1.ValidationError("Latitude must be between -90 and 90");
+        }
+        if (lng < -180 || lng > 180) {
+            throw new errors_js_1.ValidationError("Longitude must be between -180 and 180");
+        }
+        if (radius < 0 || radius > 50000) {
+            throw new errors_js_1.ValidationError("Radius must be between 0 and 50000 meters");
+        }
+        return this.client["request"]("/v1/diesel-prices/stations", {}, {
+            method: "POST",
+            body: { lat, lng, radius },
+        });
+    }
+}
+exports.DieselResource = DieselResource;

package/dist/cjs/resources/drilling.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * Drilling Intelligence Resource
+ *
+ * Access US onshore drilling activity data including rig counts, well permits,
+ * frac spreads, DUC wells, completions, and production trends by basin.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DrillingIntelligenceResource = void 0;
+const errors_js_1 = require("../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}`);
+ * ```
+ */
+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 errors_js_1.ValidationError("Basin name must be a non-empty string");
+        }
+        return this.client["request"](`/v1/drilling-intelligence/basin/${name}`, {});
+    }
+}
+exports.DrillingIntelligenceResource = DrillingIntelligenceResource;