oilpriceapi 0.7.0 → 0.9.0

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

@@ -3,6 +3,7 @@
  *
  * Access oil and gas well permit data by state, operator, and formation.
  */
+import { ValidationError } from "../../errors.js";
 /**
  * EI Well Permits Resource
  *
@@ -48,7 +49,7 @@ export class EIWellPermitsResource {
      */
     async get(id) {
         if (!id || typeof id !== "string") {
-            throw new Error("Record ID must be a non-empty string");
+            throw new ValidationError("Record ID must be a non-empty string");
         }
         return this.client["request"](`/v1/ei/well-permits/${id}`, {});
     }
@@ -103,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

@@ -4,6 +4,7 @@
  * Access official price forecasts from EIA, IEA, and other agencies including
  * monthly outlooks, accuracy metrics, and historical archives.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Forecasts Resource
  *
@@ -84,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
@@ -115,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;
     }
     /**
@@ -147,7 +154,7 @@ export class ForecastsResource {
      */
     async get(period, commodity) {
         if (!period || typeof period !== "string") {
-            throw new Error("Period must be a non-empty string");
+            throw new ValidationError("Period must be a non-empty string");
         }
         const params = {};
         if (commodity)

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

@@ -4,6 +4,142 @@
  * Access futures contract data including latest prices, historical data,
  * 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
  *
@@ -52,7 +188,7 @@ export class FuturesResource {
      */
     async latest(contract) {
         if (!contract || typeof contract !== "string") {
-            throw new Error("Contract symbol must be a non-empty string");
+            throw new ValidationError("Contract symbol must be a non-empty string");
         }
         return this.client["request"](`/v1/futures/${contract}`, {});
     }
@@ -77,7 +213,7 @@ export class FuturesResource {
      */
     async historical(contract, options) {
         if (!contract || typeof contract !== "string") {
-            throw new Error("Contract symbol must be a non-empty string");
+            throw new ValidationError("Contract symbol must be a non-empty string");
         }
         const params = {};
         if (options?.startDate)
@@ -108,7 +244,7 @@ export class FuturesResource {
      */
     async ohlc(contract, date) {
         if (!contract || typeof contract !== "string") {
-            throw new Error("Contract symbol must be a non-empty string");
+            throw new ValidationError("Contract symbol must be a non-empty string");
         }
         const params = {};
         if (date)
@@ -136,7 +272,7 @@ export class FuturesResource {
      */
     async intraday(contract) {
         if (!contract || typeof contract !== "string") {
-            throw new Error("Contract symbol must be a non-empty string");
+            throw new ValidationError("Contract symbol must be a non-empty string");
         }
         return this.client["request"](`/v1/futures/${contract}/intraday`, {});
     }
@@ -161,10 +297,10 @@ export class FuturesResource {
      */
     async spreads(contract1, contract2) {
         if (!contract1 || typeof contract1 !== "string") {
-            throw new Error("First contract symbol must be a non-empty string");
+            throw new ValidationError("First contract symbol must be a non-empty string");
         }
         if (!contract2 || typeof contract2 !== "string") {
-            throw new Error("Second contract symbol must be a non-empty string");
+            throw new ValidationError("Second contract symbol must be a non-empty string");
         }
         return this.client["request"]("/v1/futures/spreads", {
             contract1,
@@ -193,7 +329,7 @@ export class FuturesResource {
      */
     async curve(contract) {
         if (!contract || typeof contract !== "string") {
-            throw new Error("Contract symbol must be a non-empty string");
+            throw new ValidationError("Contract symbol must be a non-empty string");
         }
         return this.client["request"](`/v1/futures/${contract}/curve`, {});
     }
@@ -218,11 +354,66 @@ export class FuturesResource {
      */
     async continuous(contract, months) {
         if (!contract || typeof contract !== "string") {
-            throw new Error("Contract symbol must be a non-empty string");
+            throw new ValidationError("Contract symbol must be a non-empty string");
         }
         const params = {};
         if (months !== undefined)
             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");
+    }
 }