oilpriceapi 0.8.2 → 0.9.1

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

@@ -6,23 +6,71 @@
  */
 import type { OilPriceAPI } from "../client.js";
 /**
- * Futures contract price data
+ * A single futures contract month within a {@link FuturesPrice} response.
+ *
+ * Returned at the top level under `front_month` and for every entry in
+ * `contracts[]`. The latest traded price is `last_price`.
+ */
+export interface FuturesContractMonth {
+    /** Contract code (e.g. "BRENT_FUTURES_2026_08"). */
+    code?: string;
+    /** Contract month in YYYY-MM form (e.g. "2026-08"). */
+    contract_month?: string;
+    /** Latest traded/settlement price for this contract month. */
+    last_price?: number;
+    /** Currency code (e.g. "USD"). */
+    currency?: string;
+    /** Opening price (may be returned as a string by the API). */
+    open?: number | string;
+    /** Closing price (may be returned as a string by the API). */
+    close?: number | string;
+    /** Session high. */
+    high?: number | string;
+    /** Session low. */
+    low?: number | string;
+    /** Any additional fields the API returns for a contract month. */
+    [key: string]: unknown;
+}
+/**
+ * Futures contract price data.
+ *
+ * `GET /v1/futures/{slug}` returns a TOP-LEVEL object (there is NO
+ * `{ status, data }` envelope). The latest price lives at
+ * `front_month.last_price`, with the full term structure in `contracts[]`.
+ *
+ * Legacy flat fields (`contract`, `price`, `currency`, `timestamp`) are kept
+ * optional for backward compatibility, but real responses populate
+ * `front_month` / `contracts` instead.
  */
 export interface FuturesPrice {
-    /** Contract symbol */
-    contract: string;
-    /** Current price */
-    price: number;
-    /** Formatted price string */
+    /** Commodity identifier (e.g. "BRENT_FUTURES"). */
+    commodity?: string;
+    /** Data source (e.g. "ICE"). */
+    source?: string;
+    /** ISO timestamp the data was last updated. */
+    updated_at?: string;
+    /** Settlement date for the prices. */
+    settlement_date?: string;
+    /** Front-month contract — the latest price is `front_month.last_price`. */
+    front_month?: FuturesContractMonth;
+    /** Full forward term structure, one entry per contract month. */
+    contracts?: FuturesContractMonth[];
+    /** Optional warning when the returned data is stale. */
+    data_age_warning?: unknown;
+    /** Additional metadata returned by the API. */
+    metadata?: Record<string, unknown>;
+    /** @deprecated Legacy flat contract symbol — use `front_month.code`. */
+    contract?: string;
+    /** @deprecated Legacy flat price — use `front_month.last_price`. */
+    price?: number;
+    /** @deprecated Legacy formatted price string. */
     formatted?: string;
-    /** Currency code */
-    currency: string;
-    /** Contract expiration date */
+    /** @deprecated Legacy currency — use `front_month.currency`. */
+    currency?: string;
+    /** @deprecated Legacy contract expiration date. */
     expiration?: string;
-    /** ISO timestamp when price was recorded */
-    timestamp: string;
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
+    /** @deprecated Legacy ISO timestamp — use `updated_at`. */
+    timestamp?: string;
 }
 /**
  * Historical futures price data
@@ -40,13 +88,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
@@ -120,15 +189,25 @@ export interface FuturesCurvePoint {
     contract?: string;
 }
 /**
- * Futures curve data
+ * Futures curve data.
+ *
+ * `GET /v1/futures/{slug}/curve` can legitimately return a no-data response of
+ * the form `{ error: "No futures data available for curve analysis", date }`
+ * when a curve cannot be built. That is a valid state (not an HTTP error), so
+ * `curve` is optional and `error` / `date` are surfaced for callers to detect
+ * the no-data case.
  */
 export interface FuturesCurveData {
     /** Base contract */
-    contract: string;
+    contract?: string;
     /** ISO timestamp when curve was generated */
-    timestamp: string;
-    /** Array of curve points */
-    curve: FuturesCurvePoint[];
+    timestamp?: string;
+    /** Array of curve points (absent in the no-data response) */
+    curve?: FuturesCurvePoint[];
+    /** Present in the no-data response: "No futures data available for curve analysis". */
+    error?: string;
+    /** Date associated with the no-data response. */
+    date?: string;
 }
 /**
  * Continuous contract data point
@@ -152,6 +231,140 @@ 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}` (latest) endpoint plus the
+ * `GET /v1/futures/{slug}/...` sub-resources. Latest is the bare slug path
+ * (there is NO `/latest` suffix). Each family also supports `/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>;
+/**
+ * Resolve a futures contract code (e.g. `"BZ"`, `"QS"`) or an already-valid
+ * family slug (e.g. `"ice-brent"`) to its `/v1/futures/{slug}` path segment.
+ *
+ * Matching is case-insensitive for codes. Returns `null` if the input maps to
+ * neither a known code nor a known family slug.
+ */
+export declare function resolveFuturesFamilySlug(codeOrSlug: string): FuturesContractFamilySlug | null;
+/**
+ * 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 is served from the bare slug path `GET /v1/futures/{slug}` —
+     * there is NO `/latest` suffix (that path 404s).
+     */
+    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
  *
@@ -164,16 +377,13 @@ export interface ContinuousFuturesData {
  *
  * const client = new OilPriceAPI({ apiKey: 'your_key' });
  *
- * // Get latest price
- * const latest = await client.futures.latest('CL.1');
+ * // Get the latest curve by contract code (resolves to GET /v1/futures/ice-wti)
+ * const latest = await client.futures.latest('CL');
  * console.log(`${latest.contract}: $${latest.price}`);
  *
- * // Get OHLC data
- * const ohlc = await client.futures.ohlc('CL.1', '2024-01-15');
- * console.log(`High: $${ohlc.high}, Low: $${ohlc.low}`);
- *
- * // Get futures curve
- * const curve = await client.futures.curve('CL');
+ * // Typed family helpers are the most ergonomic option:
+ * const brent = await client.futures.brent().latest();
+ * const curve = await client.futures.brent().curve();
  * curve.curve.forEach(point => {
  *   console.log(`${point.months_out}mo: $${point.price}`);
  * });
@@ -183,18 +393,28 @@ export declare class FuturesResource {
     private client;
     constructor(client: OilPriceAPI);
     /**
-     * Get latest price for a futures contract
+     * Get the latest curve/quote for a futures contract family.
      *
-     * @param contract - Contract symbol (e.g., "CL.1", "BZ.2")
-     * @returns Latest futures price data
+     * Accepts an ergonomic contract code (e.g. `"BZ"`, `"CL"`, `"QS"`) or a
+     * family slug (e.g. `"ice-brent"`). The code is resolved to its family slug
+     * and the request is sent to `GET /v1/futures/{slug}` — the bare slug path,
+     * with NO `/latest` suffix (the suffixed path 404s).
      *
-     * @throws {NotFoundError} If contract not found
+     * Supported codes: BZ (Brent), CL (WTI), G/QS (Gasoil), NG (Natural Gas),
+     * TTF, JKM, EUA, UKA. Slugs: ice-brent, ice-wti, ice-gasoil, natural-gas,
+     * ttf-gas, lng-jkm, eua-carbon, uk-carbon.
+     *
+     * @param contract - Contract code (e.g. "BZ") or family slug (e.g. "ice-brent").
+     * @returns Latest futures price/curve data
+     *
+     * @throws {ValidationError} If the code/slug is empty or unrecognized.
      * @throws {OilPriceAPIError} If API request fails
      *
      * @example
      * ```typescript
-     * const price = await client.futures.latest('CL.1');
-     * console.log(`WTI Front Month: $${price.price}`);
+     * import { FUTURES_CONTRACTS } from 'oilpriceapi';
+     * const price = await client.futures.latest(FUTURES_CONTRACTS.BRENT); // "BZ"
+     * const wti = await client.futures.latest('ice-wti');
      * ```
      */
     latest(contract: string): Promise<FuturesPrice>;
@@ -319,4 +539,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;
 }