oilpriceapi 0.8.2 → 0.9.0

package/dist/resources/data-sources.js

@@ -120,22 +120,18 @@ export class DataSourcesResource {
         if (!params.name || typeof params.name !== "string") {
             throw new ValidationError("Data source name is required");
         }
-        if (!params.type) {
-            throw new ValidationError("Data source type is required");
-        }
-        if (!params.config || typeof params.config !== "object") {
-            throw new ValidationError("Data source config is required");
+        if (!params.source_type) {
+            throw new ValidationError("Data source source_type 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,
+                    source_type: params.source_type,
+                    status: params.status,
+                    credentials: params.credentials,
+                    scraper_config: params.scraper_config,
                 },
             },
         });
@@ -284,10 +280,15 @@ export class DataSourcesResource {
      * console.log(`Credential rotation: ${result.success ? 'success' : 'failed'}`);
      * ```
      */
-    async rotateCredentials(id) {
+    async rotateCredentials(id, credentials) {
         if (!id || typeof id !== "string") {
             throw new ValidationError("Data source ID must be a non-empty string");
         }
-        return this.client["request"](`/v1/data-sources/${id}/rotate-credentials`, {}, { method: "POST" });
+        if (!credentials || typeof credentials !== "object") {
+            throw new ValidationError("New credentials object is required");
+        }
+        // Route is POST /v1/data-sources/:id/rotate_credentials (underscore) and
+        // the controller does params.require(:credentials).
+        return this.client["request"](`/v1/data-sources/${id}/rotate_credentials`, {}, { method: "POST", body: { credentials } });
     }
 }

package/dist/resources/ei/frac-focus.d.ts

@@ -100,18 +100,32 @@ export interface WellChemical {
     mass_lbs?: number;
 }
 /**
- * FracFocus search query
+ * FracFocus search query.
+ *
+ * Maps to the parameters the `search` action actually reads. Note: `operator`
+ * and `chemical` are NOT search params (use the dedicated by-operator /
+ * by-chemical endpoints); state filtering uses `states` (comma-separated, plural).
  */
 export interface FracFocusSearchQuery {
-    /** State filter */
-    state?: string;
-    /** Operator filter */
-    operator?: string;
-    /** Chemical filter */
-    chemical?: string;
-    /** Start date */
+    /** Comma-separated state codes (e.g. 'TX,NM') */
+    states?: string;
+    /** County name (partial match) */
+    county?: string;
+    /** Well name (partial match) */
+    well_name?: string;
+    /** API well number (partial match) */
+    api_number?: string;
+    /** Minimum total base water volume (gallons) */
+    min_water_gallons?: number;
+    /** Latitude for radius search */
+    latitude?: number;
+    /** Longitude for radius search */
+    longitude?: number;
+    /** Radius in miles (1-100, default 10) for lat/lng search */
+    radius_miles?: number;
+    /** Start date (job_start_date >=) */
     start_date?: string;
-    /** End date */
+    /** End date (job_start_date <=) */
     end_date?: string;
 }
 /**

package/dist/resources/ei/frac-focus.js

@@ -109,12 +109,22 @@ export class EIFracFocusResource {
      */
     async search(query) {
         const params = {};
-        if (query.state)
-            params.state = query.state;
-        if (query.operator)
-            params.operator = query.operator;
-        if (query.chemical)
-            params.chemical = query.chemical;
+        if (query.states)
+            params.states = query.states;
+        if (query.county)
+            params.county = query.county;
+        if (query.well_name)
+            params.well_name = query.well_name;
+        if (query.api_number)
+            params.api_number = query.api_number;
+        if (query.min_water_gallons !== undefined)
+            params.min_water_gallons = query.min_water_gallons.toString();
+        if (query.latitude !== undefined)
+            params.latitude = query.latitude.toString();
+        if (query.longitude !== undefined)
+            params.longitude = query.longitude.toString();
+        if (query.radius_miles !== undefined)
+            params.radius_miles = query.radius_miles.toString();
         if (query.start_date)
             params.start_date = query.start_date;
         if (query.end_date)

package/dist/resources/ei/well-permits.d.ts

@@ -84,18 +84,34 @@ export interface PermitsByFormation {
     date: string;
 }
 /**
- * Well permit search query
+ * Well permit search query.
+ *
+ * Maps to the parameters the `search` action actually reads. Note: `operator`
+ * and `formation` are NOT search params (use the dedicated by-operator /
+ * by-formation endpoints); state filtering uses `states` (comma-separated, plural).
  */
 export interface WellPermitSearchQuery {
-    /** State filter */
-    state?: string;
-    /** Operator filter */
-    operator?: string;
-    /** Formation filter */
-    formation?: string;
-    /** Start date */
+    /** Comma-separated state codes (e.g. 'TX,NM') */
+    states?: string;
+    /** County name (partial match) */
+    county?: string;
+    /** Well name (partial match) */
+    well_name?: string;
+    /** Permit type */
+    permit_type?: string;
+    /** Well type */
+    well_type?: string;
+    /** Free-form address (geocoded to lat/lng) */
+    address?: string;
+    /** Latitude for radius search */
+    latitude?: number;
+    /** Longitude for radius search */
+    longitude?: number;
+    /** Radius in miles (1-100, default 10) for lat/lng search */
+    radius_miles?: number;
+    /** Start date (permit_date >=) */
     start_date?: string;
-    /** End date */
+    /** End date (permit_date <=) */
     end_date?: string;
 }
 /**

package/dist/resources/ei/well-permits.js

@@ -104,12 +104,24 @@ export class EIWellPermitsResource {
      */
     async search(query) {
         const params = {};
-        if (query.state)
-            params.state = query.state;
-        if (query.operator)
-            params.operator = query.operator;
-        if (query.formation)
-            params.formation = query.formation;
+        if (query.states)
+            params.states = query.states;
+        if (query.county)
+            params.county = query.county;
+        if (query.well_name)
+            params.well_name = query.well_name;
+        if (query.permit_type)
+            params.permit_type = query.permit_type;
+        if (query.well_type)
+            params.well_type = query.well_type;
+        if (query.address)
+            params.address = query.address;
+        if (query.latitude !== undefined)
+            params.latitude = query.latitude.toString();
+        if (query.longitude !== undefined)
+            params.longitude = query.longitude.toString();
+        if (query.radius_miles !== undefined)
+            params.radius_miles = query.radius_miles.toString();
         if (query.start_date)
             params.start_date = query.start_date;
         if (query.end_date)

package/dist/resources/forecasts.d.ts

@@ -172,7 +172,10 @@ export declare class ForecastsResource {
      * });
      * ```
      */
-    archive(year?: number): Promise<ArchivedForecast[]>;
+    archive(options?: {
+        page?: number;
+        perPage?: number;
+    }): Promise<ArchivedForecast[]>;
     /**
      * Get forecast for a specific period
      *

package/dist/resources/forecasts.js

@@ -85,7 +85,8 @@ export class ForecastsResource {
      * ```
      */
     async accuracy() {
-        return this.client["request"]("/v1/forecasts/accuracy", {});
+        // Route is /v1/forecasts/monthly/accuracy (the bare /accuracy 404s).
+        return this.client["request"]("/v1/forecasts/monthly/accuracy", {});
     }
     /**
      * Get archived forecasts
@@ -116,11 +117,16 @@ export class ForecastsResource {
      * });
      * ```
      */
-    async archive(year) {
+    async archive(options) {
+        // Route is /v1/forecasts/monthly/archive (the bare /archive 404s). The
+        // controller reads only `page` / `per_page` — it does NOT filter by year,
+        // so the previous `year` argument was silently ignored.
         const params = {};
-        if (year)
-            params.year = year.toString();
-        const response = await this.client["request"]("/v1/forecasts/archive", params);
+        if (options?.page !== undefined)
+            params.page = options.page.toString();
+        if (options?.perPage !== undefined)
+            params.per_page = options.perPage.toString();
+        const response = await this.client["request"]("/v1/forecasts/monthly/archive", params);
         return Array.isArray(response) ? response : response.forecasts;
     }
     /**

package/dist/resources/futures.d.ts

@@ -40,13 +40,34 @@ export interface HistoricalFuturesPrice {
     open_interest?: number;
 }
 /**
- * Options for historical futures query
+ * Options for historical futures query.
+ *
+ * The controller reads `from` / `to` (dates) plus optional `interval` and
+ * `contracts` — NOT `start_date` / `end_date`.
  */
 export interface HistoricalFuturesOptions {
     /** Start date in ISO 8601 format (YYYY-MM-DD) */
     startDate?: string;
     /** End date in ISO 8601 format (YYYY-MM-DD) */
     endDate?: string;
+    /** Aggregation interval (e.g. '1d') */
+    interval?: string;
+    /** Specific contracts to include */
+    contracts?: string;
+}
+/**
+ * Options for futures OHLC query.
+ *
+ * The controller reads `days`, `contract` and `interval` — there is no `date`
+ * parameter for OHLC.
+ */
+export interface FuturesOHLCOptions {
+    /** Number of days of OHLC bars (default 30, clamped 1-365) */
+    days?: number;
+    /** Specific contract */
+    contract?: string;
+    /** Aggregation interval */
+    interval?: string;
 }
 /**
  * OHLC (Open, High, Low, Close) data for a futures contract
@@ -152,6 +173,128 @@ export interface ContinuousFuturesData {
     /** Array of continuous prices */
     prices: ContinuousContractPrice[];
 }
+/**
+ * Spread-history data point for a contract family.
+ */
+export interface FuturesSpreadHistoryPoint {
+    /** ISO date */
+    date: string;
+    /** Spread value */
+    spread: number;
+    /** Optional percentage spread */
+    spread_percent?: number;
+}
+/**
+ * Spread-history data for a contract family.
+ */
+export interface FuturesSpreadHistory {
+    /** Contract family slug (e.g., "ice-brent") */
+    family: string;
+    /** Array of historical spread points */
+    history: FuturesSpreadHistoryPoint[];
+}
+/**
+ * Slugs for the supported ICE / gas / carbon futures contract families.
+ *
+ * These map to the `GET /v1/futures/{slug}/...` endpoints. Each family
+ * supports `/latest`, `/historical`, `/ohlc`, `/intraday`, `/spreads`,
+ * `/curve`, and `/spread-history`.
+ */
+export type FuturesContractFamilySlug = "ice-brent" | "ice-gasoil" | "ice-wti" | "natural-gas" | "ttf-gas" | "lng-jkm" | "eua-carbon" | "uk-carbon";
+/**
+ * Ergonomic contract codes for the most-requested futures families (issue #1).
+ *
+ * Use with the generic {@link FuturesResource} methods, or use the typed
+ * {@link FuturesResource.family} helper for direct access to a family's
+ * endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { FUTURES_CONTRACTS } from 'oilpriceapi';
+ *
+ * const brent = await client.futures.latest(FUTURES_CONTRACTS.BRENT); // "BZ"
+ * const gasoil = await client.futures.family('ice-gasoil').latest();
+ * ```
+ */
+export declare const FUTURES_CONTRACTS: {
+    /** ICE Brent crude */
+    readonly BRENT: "BZ";
+    /** NYMEX WTI crude */
+    readonly WTI: "CL";
+    /** ICE Gasoil */
+    readonly GASOIL: "G";
+    /** Henry Hub natural gas */
+    readonly NATURAL_GAS: "NG";
+    /** TTF natural gas (Europe) */
+    readonly TTF_GAS: "TTF";
+    /** LNG JKM (Asia) */
+    readonly LNG_JKM: "JKM";
+    /** EU carbon allowance */
+    readonly EUA_CARBON: "EUA";
+    /** UK carbon allowance */
+    readonly UK_CARBON: "UKA";
+};
+/**
+ * Mapping of ergonomic contract codes to their API contract-family slugs.
+ *
+ * Lets you resolve a contract code (e.g., `"BZ"`) to the `/v1/futures/{slug}`
+ * path segment used by the typed family helpers.
+ */
+export declare const FUTURES_FAMILY_SLUGS: Record<string, FuturesContractFamilySlug>;
+/**
+ * Typed helper for a single futures contract family (e.g., ICE Brent, Gasoil).
+ *
+ * Provides ergonomic access to the family's endpoints without having to
+ * remember the URL slug. Obtain an instance via {@link FuturesResource.family},
+ * {@link FuturesResource.brent}, {@link FuturesResource.gasoil}, etc.
+ *
+ * @example
+ * ```typescript
+ * const gasoil = client.futures.gasoil();
+ * const latest = await gasoil.latest();
+ * const curve = await gasoil.curve();
+ * ```
+ */
+export declare class FuturesContractFamily {
+    private client;
+    /** The contract-family slug used in the API path. */
+    readonly slug: FuturesContractFamilySlug;
+    constructor(client: OilPriceAPI, 
+    /** The contract-family slug used in the API path. */
+    slug: FuturesContractFamilySlug);
+    /**
+     * Get the latest price for this contract family.
+     */
+    latest(): Promise<FuturesPrice>;
+    /**
+     * Get historical prices for this contract family.
+     *
+     * @param options - Optional date range filters.
+     */
+    historical(options?: HistoricalFuturesOptions): Promise<HistoricalFuturesPrice[]>;
+    /**
+     * Get OHLC data for this contract family.
+     *
+     * @param options - `{ days, contract, interval }` (the API has no `date` param here).
+     */
+    ohlc(options?: FuturesOHLCOptions): Promise<FuturesOHLC>;
+    /**
+     * Get intraday price data for this contract family.
+     */
+    intraday(): Promise<IntradayFuturesData>;
+    /**
+     * Get the spreads for this contract family.
+     */
+    spreads(): Promise<FuturesSpread[]>;
+    /**
+     * Get the forward curve for this contract family.
+     */
+    curve(): Promise<FuturesCurveData>;
+    /**
+     * Get historical spread data for this contract family.
+     */
+    spreadHistory(): Promise<FuturesSpreadHistory>;
+}
 /**
  * Futures Resource
  *
@@ -319,4 +462,38 @@ export declare class FuturesResource {
      * ```
      */
     continuous(contract: string, months?: number): Promise<ContinuousFuturesData>;
+    /**
+     * Get a typed helper for a specific contract family (issue #1).
+     *
+     * Provides ergonomic access to the ICE Brent / WTI / Gasoil and gas/carbon
+     * family endpoints (`/latest`, `/historical`, `/ohlc`, `/intraday`,
+     * `/spreads`, `/curve`, `/spread-history`) without remembering the URL slug.
+     *
+     * @param slug - Contract family slug (e.g., `"ice-brent"`, `"ice-gasoil"`).
+     * @returns A {@link FuturesContractFamily} bound to the slug.
+     *
+     * @example
+     * ```typescript
+     * const brent = client.futures.family('ice-brent');
+     * const latest = await brent.latest();
+     * const curve = await brent.curve();
+     * ```
+     */
+    family(slug: FuturesContractFamilySlug): FuturesContractFamily;
+    /** ICE Brent crude futures family helper (issue #1). */
+    brent(): FuturesContractFamily;
+    /** ICE WTI crude futures family helper. */
+    wti(): FuturesContractFamily;
+    /** ICE Gasoil futures family helper (issue #1). */
+    gasoil(): FuturesContractFamily;
+    /** Henry Hub natural gas futures family helper. */
+    naturalGas(): FuturesContractFamily;
+    /** TTF natural gas (Europe) futures family helper. */
+    ttfGas(): FuturesContractFamily;
+    /** LNG JKM (Asia) futures family helper. */
+    lngJkm(): FuturesContractFamily;
+    /** EU carbon allowance (EUA) futures family helper. */
+    euaCarbon(): FuturesContractFamily;
+    /** UK carbon allowance (UKA) futures family helper. */
+    ukCarbon(): FuturesContractFamily;
 }

package/dist/resources/futures.js

@@ -5,6 +5,141 @@
  * OHLC, intraday, spreads, curves, and continuous contracts.
  */
 import { ValidationError } from "../errors.js";
+/**
+ * Ergonomic contract codes for the most-requested futures families (issue #1).
+ *
+ * Use with the generic {@link FuturesResource} methods, or use the typed
+ * {@link FuturesResource.family} helper for direct access to a family's
+ * endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { FUTURES_CONTRACTS } from 'oilpriceapi';
+ *
+ * const brent = await client.futures.latest(FUTURES_CONTRACTS.BRENT); // "BZ"
+ * const gasoil = await client.futures.family('ice-gasoil').latest();
+ * ```
+ */
+export const FUTURES_CONTRACTS = {
+    /** ICE Brent crude */
+    BRENT: "BZ",
+    /** NYMEX WTI crude */
+    WTI: "CL",
+    /** ICE Gasoil */
+    GASOIL: "G",
+    /** Henry Hub natural gas */
+    NATURAL_GAS: "NG",
+    /** TTF natural gas (Europe) */
+    TTF_GAS: "TTF",
+    /** LNG JKM (Asia) */
+    LNG_JKM: "JKM",
+    /** EU carbon allowance */
+    EUA_CARBON: "EUA",
+    /** UK carbon allowance */
+    UK_CARBON: "UKA",
+};
+/**
+ * Mapping of ergonomic contract codes to their API contract-family slugs.
+ *
+ * Lets you resolve a contract code (e.g., `"BZ"`) to the `/v1/futures/{slug}`
+ * path segment used by the typed family helpers.
+ */
+export const FUTURES_FAMILY_SLUGS = {
+    [FUTURES_CONTRACTS.BRENT]: "ice-brent",
+    [FUTURES_CONTRACTS.WTI]: "ice-wti",
+    [FUTURES_CONTRACTS.GASOIL]: "ice-gasoil",
+    [FUTURES_CONTRACTS.NATURAL_GAS]: "natural-gas",
+    [FUTURES_CONTRACTS.TTF_GAS]: "ttf-gas",
+    [FUTURES_CONTRACTS.LNG_JKM]: "lng-jkm",
+    [FUTURES_CONTRACTS.EUA_CARBON]: "eua-carbon",
+    [FUTURES_CONTRACTS.UK_CARBON]: "uk-carbon",
+};
+/**
+ * Typed helper for a single futures contract family (e.g., ICE Brent, Gasoil).
+ *
+ * Provides ergonomic access to the family's endpoints without having to
+ * remember the URL slug. Obtain an instance via {@link FuturesResource.family},
+ * {@link FuturesResource.brent}, {@link FuturesResource.gasoil}, etc.
+ *
+ * @example
+ * ```typescript
+ * const gasoil = client.futures.gasoil();
+ * const latest = await gasoil.latest();
+ * const curve = await gasoil.curve();
+ * ```
+ */
+export class FuturesContractFamily {
+    constructor(client, 
+    /** The contract-family slug used in the API path. */
+    slug) {
+        this.client = client;
+        this.slug = slug;
+    }
+    /**
+     * Get the latest price for this contract family.
+     */
+    async latest() {
+        return this.client["request"](`/v1/futures/${this.slug}/latest`, {});
+    }
+    /**
+     * Get historical prices for this contract family.
+     *
+     * @param options - Optional date range filters.
+     */
+    async historical(options) {
+        const params = {};
+        if (options?.startDate)
+            params.from = options.startDate;
+        if (options?.endDate)
+            params.to = options.endDate;
+        if (options?.interval)
+            params.interval = options.interval;
+        if (options?.contracts)
+            params.contracts = options.contracts;
+        const response = await this.client["request"](`/v1/futures/${this.slug}/historical`, params);
+        return Array.isArray(response) ? response : response.prices;
+    }
+    /**
+     * Get OHLC data for this contract family.
+     *
+     * @param options - `{ days, contract, interval }` (the API has no `date` param here).
+     */
+    async ohlc(options) {
+        const params = {};
+        if (options?.days !== undefined)
+            params.days = options.days.toString();
+        if (options?.contract)
+            params.contract = options.contract;
+        if (options?.interval)
+            params.interval = options.interval;
+        return this.client["request"](`/v1/futures/${this.slug}/ohlc`, params);
+    }
+    /**
+     * Get intraday price data for this contract family.
+     */
+    async intraday() {
+        return this.client["request"](`/v1/futures/${this.slug}/intraday`, {});
+    }
+    /**
+     * Get the spreads for this contract family.
+     */
+    async spreads() {
+        const response = await this.client["request"](`/v1/futures/${this.slug}/spreads`, {});
+        return Array.isArray(response) ? response : response.data;
+    }
+    /**
+     * Get the forward curve for this contract family.
+     */
+    async curve() {
+        return this.client["request"](`/v1/futures/${this.slug}/curve`, {});
+    }
+    /**
+     * Get historical spread data for this contract family.
+     */
+    async spreadHistory() {
+        return this.client["request"](`/v1/futures/${this.slug}/spread-history`, {});
+    }
+}
 /**
  * Futures Resource
  *
@@ -226,4 +361,59 @@ export class FuturesResource {
             params.months = months.toString();
         return this.client["request"](`/v1/futures/${contract}/continuous`, params);
     }
+    /**
+     * Get a typed helper for a specific contract family (issue #1).
+     *
+     * Provides ergonomic access to the ICE Brent / WTI / Gasoil and gas/carbon
+     * family endpoints (`/latest`, `/historical`, `/ohlc`, `/intraday`,
+     * `/spreads`, `/curve`, `/spread-history`) without remembering the URL slug.
+     *
+     * @param slug - Contract family slug (e.g., `"ice-brent"`, `"ice-gasoil"`).
+     * @returns A {@link FuturesContractFamily} bound to the slug.
+     *
+     * @example
+     * ```typescript
+     * const brent = client.futures.family('ice-brent');
+     * const latest = await brent.latest();
+     * const curve = await brent.curve();
+     * ```
+     */
+    family(slug) {
+        if (!slug || typeof slug !== "string") {
+            throw new ValidationError("Contract family slug must be a non-empty string");
+        }
+        return new FuturesContractFamily(this.client, slug);
+    }
+    /** ICE Brent crude futures family helper (issue #1). */
+    brent() {
+        return this.family("ice-brent");
+    }
+    /** ICE WTI crude futures family helper. */
+    wti() {
+        return this.family("ice-wti");
+    }
+    /** ICE Gasoil futures family helper (issue #1). */
+    gasoil() {
+        return this.family("ice-gasoil");
+    }
+    /** Henry Hub natural gas futures family helper. */
+    naturalGas() {
+        return this.family("natural-gas");
+    }
+    /** TTF natural gas (Europe) futures family helper. */
+    ttfGas() {
+        return this.family("ttf-gas");
+    }
+    /** LNG JKM (Asia) futures family helper. */
+    lngJkm() {
+        return this.family("lng-jkm");
+    }
+    /** EU carbon allowance (EUA) futures family helper. */
+    euaCarbon() {
+        return this.family("eua-carbon");
+    }
+    /** UK carbon allowance (UKA) futures family helper. */
+    ukCarbon() {
+        return this.family("uk-carbon");
+    }
 }