oilpriceapi 0.7.0 → 0.9.0

package/README.md

@@ -1,9 +1,15 @@
 # Oil Price API - Node.js SDK
 
+> **Real-time oil and commodity price data for Node.js** - Professional-grade API at 98% less cost than Bloomberg Terminal
+
 [![npm version](https://badge.fury.io/js/oilpriceapi.svg)](https://www.npmjs.com/package/oilpriceapi)
+[![npm downloads](https://img.shields.io/npm/dm/oilpriceapi)](https://www.npmjs.com/package/oilpriceapi)
+[![Tests](https://github.com/OilpriceAPI/oilpriceapi-node/actions/workflows/test.yml/badge.svg)](https://github.com/OilpriceAPI/oilpriceapi-node/actions/workflows/test.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Official Node.js SDK for [Oil Price API](https://www.oilpriceapi.com) - Get real-time and historical oil & commodity prices.
+**[Get Free API Key](https://www.oilpriceapi.com/signup?utm_source=npm&utm_medium=sdk&utm_campaign=readme)** | **[Documentation](https://docs.oilpriceapi.com)** | **[Pricing](https://www.oilpriceapi.com/pricing?utm_source=npm&utm_medium=sdk&utm_campaign=pricing)**
+
+The official Node.js/TypeScript SDK for [OilPriceAPI](https://www.oilpriceapi.com) - Real-time and historical oil prices for Brent Crude, WTI, Natural Gas, and 100+ commodities.
 
 ## Features
 
@@ -19,6 +25,7 @@ Official Node.js SDK for [Oil Price API](https://www.oilpriceapi.com) - Get real
 - ⛽ **NEW v0.4.0** - Diesel prices (state averages + station-level pricing)
 - 🔔 **NEW v0.5.0** - Price alerts with webhook notifications
 - 📊 **NEW v0.7.0** - Futures, storage, rig counts, analytics, drilling intelligence, webhooks, and energy intelligence
+- 🧰 **NEW** - Typed ICE Brent / Gasoil / WTI & gas/carbon futures helpers, `spreads`, `indicators`, and raw HTTP responses (`client.raw.*` with status + headers)
 
 ## Installation
 
@@ -33,7 +40,7 @@ import { OilPriceAPI } from "oilpriceapi";
 
 // Initialize the client
 const client = new OilPriceAPI({
-  apiKey: "your_api_key_here", // Get your free key at https://www.oilpriceapi.com
+  apiKey: "your_api_key_here", // Get your free key at https://www.oilpriceapi.com/signup
   retries: 3, // Automatic retries (default: 3)
   timeout: 30000, // Request timeout in ms (default: 30000)
 });
@@ -261,9 +268,7 @@ console.log("Alert deleted successfully");
 const result = await client.alerts.testWebhook("https://your-app.com/webhook");
 
 if (result.success) {
-  console.log(
-    `Webhook OK (${result.status_code}) - ${result.response_time_ms}ms`,
-  );
+  console.log(`Webhook OK (${result.status_code}) - ${result.response_time_ms}ms`);
 } else {
   console.error(`Webhook failed: ${result.error}`);
 }
@@ -335,6 +340,138 @@ curve.curve.forEach((point) => {
 });
 ```
 
+#### Typed contract-family helpers (ICE Brent, Gasoil, WTI, gas & carbon)
+
+The generic `futures.*` methods take raw contract codes. For the most-requested
+families you can use ergonomic, typed helpers that map to the
+`/v1/futures/{family}/...` endpoints — no need to remember URL slugs. Each
+family supports `latest`, `historical`, `ohlc`, `intraday`, `spreads`, `curve`,
+and `spreadHistory`.
+
+```typescript
+import { OilPriceAPI, FUTURES_CONTRACTS } from "oilpriceapi";
+
+const client = new OilPriceAPI({ apiKey: "your_key" });
+
+// ICE Brent
+const brent = await client.futures.brent().latest();
+console.log(`Brent: $${brent.price}`);
+
+// ICE Gasoil
+const gasoil = await client.futures.gasoil().curve();
+
+// ICE WTI
+const wti = await client.futures.wti().ohlc("2024-01-15");
+
+// Natural gas families
+await client.futures.naturalGas().latest(); // Henry Hub
+await client.futures.ttfGas().historical({ startDate: "2024-01-01" }); // TTF (Europe)
+await client.futures.lngJkm().spreads(); // LNG JKM (Asia)
+
+// Carbon
+await client.futures.euaCarbon().latest(); // EU carbon allowance
+await client.futures.ukCarbon().spreadHistory(); // UK carbon allowance
+
+// Or address a family by slug
+const fam = client.futures.family("ice-brent");
+await fam.intraday();
+
+// Ergonomic contract-code constants for the generic methods
+const brentLatest = await client.futures.latest(FUTURES_CONTRACTS.BRENT); // "BZ"
+const gasoilCode = FUTURES_CONTRACTS.GASOIL; // "G"
+```
+
+Available families: `ice-brent`, `ice-gasoil`, `ice-wti`, `natural-gas`,
+`ttf-gas`, `lng-jkm`, `eua-carbon`, `uk-carbon`.
+
+### Spreads
+
+Crack spreads, basis differentials, curve structure (contango/backwardation),
+refining margins, and physical premiums. Each spread type supports the latest
+value, full history, and an `all` listing
+(`/v1/spreads/{type}`, `/v1/spreads/{type}/historical`, `/v1/spreads/{type}/all`).
+
+```typescript
+// Latest values via named helpers
+const crack = await client.spreads.crack();
+console.log(`Crack spread: ${crack.value} ${crack.unit}`);
+
+await client.spreads.basis();
+await client.spreads.curveStructure();
+await client.spreads.margin();
+await client.spreads.physicalPremium();
+
+// Or address a type directly
+const margin = await client.spreads.get("margin");
+
+// Historical spread series
+const history = await client.spreads.historical("basis", {
+  startDate: "2024-01-01",
+  endDate: "2024-12-31",
+});
+
+// All values for a spread type
+const allCrack = await client.spreads.all("crack");
+```
+
+### Indicators
+
+Derived market indicators and signals: fuel-switching economics, price context,
+storage analytics, market annotations, CFTC positioning, and congressional
+energy-sector trades (`/v1/indicators/{type}`).
+
+```typescript
+// Fuel-switching economics
+const fs = await client.indicators.fuelSwitching();
+console.log(`Switching economical: ${fs.economical}`);
+
+// Where the current price sits historically
+const ctx = await client.indicators.priceContext();
+console.log(`Percentile: ${ctx.percentile}`);
+
+// Storage analytics
+await client.indicators.storageAnalytics();
+
+// Market annotations (notable events)
+const annotations = await client.indicators.annotations();
+
+// CFTC positioning (Commitment of Traders)
+const cftc = await client.indicators.cftcPositioning();
+cftc.forEach((p) => console.log(`${p.market}: net ${p.net_position}`));
+
+// Congressional energy-sector trades
+const trades = await client.indicators.congressionalTrades();
+
+// Or address a type directly
+const custom = await client.indicators.get("price-context");
+```
+
+### Raw HTTP responses (status + headers)
+
+By default the SDK returns just the parsed data. When you also need the
+underlying HTTP status code and response headers (e.g. rate-limit headers),
+use the `client.raw.*` accessor. It returns `{ data, status, headers }` while
+`data` keeps the exact same shape as the equivalent non-raw method.
+
+```typescript
+const { data, status, headers } = await client.raw.getLatestPrices({
+  commodity: "WTI_USD",
+});
+
+console.log(`HTTP ${status}`);
+console.log(`Rate limit remaining: ${headers.get("x-ratelimit-remaining")}`);
+console.log(`Price: ${data[0].price}`);
+
+// Also available: getHistoricalPrices, getCommodities,
+// getCommodityCategories, getCommodity
+const commodities = await client.raw.getCommodities();
+console.log(commodities.status, commodities.headers.get("content-type"));
+
+// Generic raw GET for any endpoint without a dedicated helper
+const futures = await client.raw.get("/v1/futures/CL.1");
+console.log(futures.status, futures.data);
+```
+
 ### Storage Levels (New in v0.7.0)
 
 ```typescript
@@ -377,11 +514,7 @@ console.log(`30-day return: ${perf.return_percent}%`);
 console.log(`Volatility: ${perf.volatility}`);
 
 // Analyze correlation between commodities
-const corr = await client.analytics.correlation(
-  "WTI_USD",
-  "BRENT_CRUDE_USD",
-  90,
-);
+const corr = await client.analytics.correlation("WTI_USD", "BRENT_CRUDE_USD", 90);
 console.log(`Correlation: ${corr.correlation} (${corr.strength})`);
 ```
 
@@ -504,12 +637,73 @@ console.log(`Connection ${test.success ? "OK" : "failed"}`);
 // View sync logs
 const logs = await client.dataSources.logs(source.id);
 logs.forEach((log) => {
-  console.log(
-    `${log.timestamp}: ${log.status} - ${log.records_synced} records`,
-  );
+  console.log(`${log.timestamp}: ${log.status} - ${log.records_synced} records`);
 });
 ```
 
+### Real-time Streaming (WebSocket)
+
+Stream live price updates over a persistent WebSocket connection instead of
+polling. Streaming uses the server's ActionCable `/cable` endpoint and the
+`EnergyPricesChannel`, and is available on the **Reservoir Mastery
+(Professional+)** plan.
+
+The `client.stream.prices()` method returns a subscription handle (an
+`EventEmitter`). It performs the ActionCable handshake, answers server pings,
+auto-reconnects with exponential backoff, and surfaces typed events. Call
+`.close()` for a clean teardown.
+
+```typescript
+import { OilPriceAPI } from "oilpriceapi";
+
+const client = new OilPriceAPI({ apiKey: process.env.OILPRICEAPI_KEY });
+
+// Optional onUpdate callback fires on every live price_update.
+const sub = client.stream.prices(
+  { commodities: ["WTI_USD", "BRENT_CRUDE_USD"] }, // optional client-side filter
+  (update) => {
+    const wti = update.prices.oil.wti;
+    if (wti) {
+      console.log(`WTI ${wti.original_price} ${wti.original_currency} @ ${update.timestamp}`);
+    }
+  },
+);
+
+// Lifecycle + typed events
+sub.on("connected", () => console.log("subscription confirmed"));
+sub.on("welcome", (snapshot) => console.log("initial snapshot", snapshot.data));
+sub.on("price_update", (update) => console.log("oil:", update.prices.oil));
+sub.on("rig_count_update", (m) => console.log(`${m.rig_count.region}: ${m.rig_count.count} rigs`));
+sub.on("reconnecting", ({ attempt, delay }) => console.log(`reconnect #${attempt} in ${delay}ms`));
+sub.on("disconnected", ({ code }) => console.log("socket closed", code));
+sub.on("error", (err) => console.error("stream error:", err.message));
+
+// Clean teardown (unsubscribe + close socket)
+process.on("SIGINT", () => {
+  sub.close();
+  process.exit(0);
+});
+```
+
+**Events emitted by the subscription handle:**
+
+| Event              | Payload                 | Description                                            |
+| ------------------ | ----------------------- | ------------------------------------------------------ |
+| `connected`        | —                       | Channel subscription confirmed by the server           |
+| `welcome`          | `WelcomeMessage`        | Initial price snapshot sent on subscribe               |
+| `price_update`     | `PriceUpdateMessage`    | Live price broadcast (oil + natural gas)               |
+| `rig_count_update` | `RigCountUpdateMessage` | Drilling rig-count broadcast (drilling-tier accounts)  |
+| `message`          | `StreamMessage`         | Every decoded channel message (incl. unknown types)    |
+| `reconnecting`     | `{ attempt, delay }`    | A reconnect attempt has been scheduled                 |
+| `disconnected`     | `{ code, reason }`      | The transport closed                                   |
+| `error`            | `Error`                 | Transport error, rejected subscription, or retries out |
+| `close`            | —                       | The subscription was closed via `.close()`             |
+
+**Options** (`StreamPricesOptions`): `commodities`, `autoReconnect`,
+`reconnectDelay`, `maxReconnectDelay`, `maxReconnectAttempts`.
+
+See [`examples/streaming.ts`](./examples/streaming.ts) for a complete runnable example.
+
 ### Advanced Configuration
 
 ```typescript
@@ -551,11 +745,7 @@ try {
   if (error instanceof AuthenticationError) {
     console.error("Invalid API key:", error.message);
   } else if (error instanceof RateLimitError) {
-    console.error(
-      "Rate limit exceeded. Retry after:",
-      error.retryAfter,
-      "seconds",
-    );
+    console.error("Rate limit exceeded. Retry after:", error.retryAfter, "seconds");
   } else if (error instanceof TimeoutError) {
     console.error("Request timed out:", error.message);
   } else if (error instanceof ServerError) {
@@ -706,7 +896,7 @@ new OilPriceAPI(config: OilPriceAPIConfig)
 
 **Parameters:**
 
-- `config.apiKey` (string, required) - Your API key from https://www.oilpriceapi.com
+- `config.apiKey` (string, required) - Your API key from https://www.oilpriceapi.com/signup
 - `config.baseUrl` (string, optional) - Custom API base URL (for testing)
 
 #### Methods
@@ -806,9 +996,7 @@ const result = await client.diesel.getStations({
 console.log(`Found ${result.stations.length} stations`);
 console.log(`Regional average: $${result.regional_average.price}/gallon`);
 
-const cheapest = result.stations.reduce((min, s) =>
-  s.diesel_price < min.diesel_price ? s : min,
-);
+const cheapest = result.stations.reduce((min, s) => (s.diesel_price < min.diesel_price ? s : min));
 console.log(`Cheapest: ${cheapest.name} at ${cheapest.formatted_price}`);
 ```
 
@@ -928,7 +1116,7 @@ See the [full list of 79 commodities](https://www.oilpriceapi.com/commodities) i
 - **Business**: 200,000 requests/month - $199/mo
 - **Enterprise**: Custom limits - Contact us
 
-Get started with a free API key at [oilpriceapi.com](https://www.oilpriceapi.com).
+Get started with a free API key at [oilpriceapi.com/signup](https://www.oilpriceapi.com/signup?utm_source=npm&utm_medium=sdk&utm_campaign=readme).
 
 ## Requirements
 
@@ -950,10 +1138,9 @@ We welcome contributions! Please see our [Contributing Guide](https://github.com
 
 ## Support
 
-- 📧 Email: support@oilpriceapi.com
-- 🐛 Issues: [GitHub Issues](https://github.com/OilpriceAPI/oilpriceapi-node/issues)
-- 📚 Documentation: [oilpriceapi.com/docs](https://www.oilpriceapi.com/docs)
-- 💬 Discord: [Join our community](https://discord.gg/oilpriceapi)
+- Email: support@oilpriceapi.com
+- Issues: [GitHub Issues](https://github.com/OilpriceAPI/oilpriceapi-node/issues)
+- Docs: [Documentation](https://docs.oilpriceapi.com)
 
 ## License
 
@@ -961,11 +1148,38 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 ## Links
 
-- [Website](https://www.oilpriceapi.com)
-- [API Documentation](https://www.oilpriceapi.com/docs)
+- [OilPriceAPI Website](https://www.oilpriceapi.com)
+- [API Documentation](https://docs.oilpriceapi.com)
+- [Pricing](https://www.oilpriceapi.com/pricing?utm_source=npm&utm_medium=sdk&utm_campaign=pricing)
+- [Status Page](https://status.oilpriceapi.com)
 - [GitHub Repository](https://github.com/OilpriceAPI/oilpriceapi-node)
 - [npm Package](https://www.npmjs.com/package/oilpriceapi)
 
 ---
 
-Made with ❤️ by the Oil Price API team
+## Why OilPriceAPI?
+
+[OilPriceAPI](https://www.oilpriceapi.com) provides professional-grade commodity price data at **98% less cost than Bloomberg Terminal** ($24,000/year vs $45/month). Trusted by energy traders, financial analysts, and developers worldwide.
+
+### Key Benefits
+
+- **Real-time data** updated every 5 minutes
+- **Historical data** for trend analysis and backtesting
+- **99.9% uptime** with enterprise-grade reliability
+- **5-minute integration** with this Node.js SDK
+- **Free tier** with 100 requests to get started
+
+**[Start Free](https://www.oilpriceapi.com/signup?utm_source=npm&utm_medium=sdk&utm_campaign=readme)** | **[View Pricing](https://www.oilpriceapi.com/pricing?utm_source=npm&utm_medium=sdk&utm_campaign=pricing)** | **[Read Docs](https://docs.oilpriceapi.com)**
+
+---
+
+## Also Available As
+
+- **[Python SDK](https://pypi.org/project/oilpriceapi/)** - Python client with Pandas integration
+- **[Go SDK](https://github.com/OilpriceAPI/oilpriceapi-go)** - Idiomatic Go client
+- **[MCP Server](https://www.npmjs.com/package/oilpriceapi-mcp)** - Model Context Protocol server for Claude, Cursor, and VS Code
+- **[Google Sheets Add-on](https://github.com/OilpriceAPI/google-sheets-addin)** - Custom functions for spreadsheets
+
+---
+
+Made with care by the OilPriceAPI Team