oilpriceapi 0.6.0 → 0.8.2

package/dist/resources/webhooks.js

@@ -0,0 +1,290 @@
+/**
+ * Webhooks Resource
+ *
+ * Manage webhook endpoints for real-time event notifications.
+ */
+import { ValidationError } from "../errors.js";
+import { verifyWebhookSignature } from "../index.js";
+/**
+ * Webhooks Resource
+ *
+ * Manage webhook endpoints for real-time notifications about price changes,
+ * alerts, and other events.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Create a webhook
+ * const webhook = await client.webhooks.create({
+ *   name: 'Price Updates',
+ *   url: 'https://myapp.com/webhooks/prices',
+ *   events: ['price.updated', 'alert.triggered'],
+ *   enabled: true
+ * });
+ *
+ * // Test the webhook
+ * const test = await client.webhooks.test(webhook.id);
+ * console.log(`Test result: ${test.success ? 'passed' : 'failed'}`);
+ *
+ * // List all webhooks
+ * const webhooks = await client.webhooks.list();
+ * webhooks.forEach(wh => {
+ *   console.log(`${wh.name}: ${wh.successful_deliveries} successful`);
+ * });
+ *
+ * // Update webhook
+ * await client.webhooks.update(webhook.id, {
+ *   enabled: false
+ * });
+ *
+ * // Delete webhook
+ * await client.webhooks.delete(webhook.id);
+ * ```
+ */
+export class WebhooksResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all webhook endpoints
+     *
+     * @returns Array of webhook endpoints
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const webhooks = await client.webhooks.list();
+     * webhooks.forEach(wh => {
+     *   console.log(`${wh.name} (${wh.enabled ? 'enabled' : 'disabled'})`);
+     *   console.log(`  Events: ${wh.events.join(', ')}`);
+     * });
+     * ```
+     */
+    async list() {
+        const response = await this.client["request"]("/v1/webhooks", {});
+        return Array.isArray(response) ? response : response.webhooks;
+    }
+    /**
+     * Get a specific webhook endpoint
+     *
+     * @param id - Webhook ID
+     * @returns Webhook endpoint details
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.get('webhook-id');
+     * console.log(`${webhook.name}: ${webhook.url}`);
+     * console.log(`Success rate: ${webhook.successful_deliveries}/${webhook.successful_deliveries + webhook.failed_deliveries}`);
+     * ```
+     */
+    async get(id) {
+        if (!id || typeof id !== "string") {
+            throw new ValidationError("Webhook ID must be a non-empty string");
+        }
+        const response = await this.client["request"](`/v1/webhooks/${id}`, {});
+        return "webhook" in response ? response.webhook : response;
+    }
+    /**
+     * Create a new webhook endpoint
+     *
+     * @param params - Webhook configuration
+     * @returns Created webhook endpoint
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const webhook = await client.webhooks.create({
+     *   name: 'Production Alerts',
+     *   url: 'https://api.myapp.com/webhooks',
+     *   events: ['alert.triggered', 'price.updated'],
+     *   secret: 'my-webhook-secret',
+     *   enabled: true
+     * });
+     * console.log(`Webhook created: ${webhook.id}`);
+     * ```
+     */
+    async create(params) {
+        if (!params.name || typeof params.name !== "string") {
+            throw new ValidationError("Webhook name is required");
+        }
+        if (!params.url || !params.url.startsWith("https://")) {
+            throw new ValidationError("Webhook URL must use HTTPS protocol");
+        }
+        if (!params.events || !Array.isArray(params.events) || params.events.length === 0) {
+            throw new ValidationError("At least one event type is required");
+        }
+        const response = await this.client["request"]("/v1/webhooks", {}, {
+            method: "POST",
+            body: {
+                webhook: {
+                    name: params.name,
+                    url: params.url,
+                    events: params.events,
+                    enabled: params.enabled ?? true,
+                    secret: params.secret,
+                    metadata: params.metadata,
+                },
+            },
+        });
+        return "webhook" in response ? response.webhook : response;
+    }
+    /**
+     * Update a webhook endpoint
+     *
+     * @param id - Webhook ID
+     * @param params - Fields to update
+     * @returns Updated webhook endpoint
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * // Disable a webhook
+     * await client.webhooks.update(webhookId, { enabled: false });
+     *
+     * // Change events
+     * await client.webhooks.update(webhookId, {
+     *   events: ['alert.triggered']
+     * });
+     * ```
+     */
+    async update(id, params) {
+        if (!id || typeof id !== "string") {
+            throw new ValidationError("Webhook ID must be a non-empty string");
+        }
+        if (params.url !== undefined && !params.url.startsWith("https://")) {
+            throw new ValidationError("Webhook URL must use HTTPS protocol");
+        }
+        if (params.events !== undefined &&
+            (!Array.isArray(params.events) || params.events.length === 0)) {
+            throw new ValidationError("Events must be a non-empty array");
+        }
+        const response = await this.client["request"](`/v1/webhooks/${id}`, {}, {
+            method: "PATCH",
+            body: { webhook: params },
+        });
+        return "webhook" in response ? response.webhook : response;
+    }
+    /**
+     * Delete a webhook endpoint
+     *
+     * @param id - Webhook ID
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * await client.webhooks.delete(webhookId);
+     * console.log('Webhook deleted');
+     * ```
+     */
+    async delete(id) {
+        if (!id || typeof id !== "string") {
+            throw new ValidationError("Webhook ID must be a non-empty string");
+        }
+        await this.client["request"](`/v1/webhooks/${id}`, {}, { method: "DELETE" });
+    }
+    /**
+     * Test a webhook endpoint
+     *
+     * Sends a test payload to the webhook URL to verify it's reachable.
+     *
+     * @param id - Webhook ID
+     * @returns Test results
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const test = await client.webhooks.test(webhookId);
+     * console.log(`Test ${test.success ? 'passed' : 'failed'}`);
+     * console.log(`Response time: ${test.response_time_ms}ms`);
+     * if (!test.success) {
+     *   console.log(`Error: ${test.error}`);
+     * }
+     * ```
+     */
+    async test(id) {
+        if (!id || typeof id !== "string") {
+            throw new ValidationError("Webhook ID must be a non-empty string");
+        }
+        return this.client["request"](`/v1/webhooks/${id}/test`, {}, { method: "POST" });
+    }
+    /**
+     * Get webhook event history
+     *
+     * Returns recent delivery events for a webhook.
+     *
+     * @param id - Webhook ID
+     * @returns Array of webhook events
+     *
+     * @throws {NotFoundError} If webhook not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const events = await client.webhooks.events(webhookId);
+     * events.forEach(event => {
+     *   console.log(`${event.event_type}: ${event.status} (${event.attempts} attempts)`);
+     * });
+     * ```
+     */
+    async events(id) {
+        if (!id || typeof id !== "string") {
+            throw new ValidationError("Webhook ID must be a non-empty string");
+        }
+        const response = await this.client["request"](`/v1/webhooks/${id}/events`, {});
+        return Array.isArray(response) ? response : response.events;
+    }
+    /**
+     * Verify a webhook signature.
+     *
+     * Validates that a webhook payload was sent by OilPriceAPI by checking
+     * the HMAC-SHA256 signature. Uses constant-time comparison to prevent
+     * timing attacks.
+     *
+     * @param payload - Raw request body (string or Buffer)
+     * @param signature - Value of the X-OilPriceAPI-Signature header (e.g., "sha256=abc123...")
+     * @param secret - Your webhook signing secret
+     * @returns true if signature is valid
+     *
+     * @example
+     * ```typescript
+     * import express from 'express';
+     * import { OilPriceAPI } from 'oilpriceapi';
+     *
+     * const app = express();
+     * const client = new OilPriceAPI({ apiKey: 'your_key' });
+     *
+     * // Use raw body parser for webhook routes
+     * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+     *   const signature = req.headers['x-oilpriceapi-signature'] as string;
+     *   const isValid = client.webhooks.verifySignature(req.body, signature, 'your_secret');
+     *
+     *   if (!isValid) {
+     *     return res.status(401).send('Invalid signature');
+     *   }
+     *
+     *   const event = JSON.parse(req.body.toString());
+     *   console.log('Verified webhook:', event.type);
+     *   res.sendStatus(200);
+     * });
+     * ```
+     */
+    verifySignature(payload, signature, secret) {
+        return verifyWebhookSignature(payload, signature, secret);
+    }
+}

package/dist/types.d.ts

@@ -1,15 +1,16 @@
 /**
  * Retry backoff strategy
  */
-export type RetryStrategy = 'exponential' | 'linear' | 'fixed';
+export type RetryStrategy = "exponential" | "linear" | "fixed";
 /**
  * Configuration options for OilPriceAPI client
  */
 export interface OilPriceAPIConfig {
     /**
      * Your API key from https://www.oilpriceapi.com
+     * If not provided, reads from OILPRICEAPI_KEY environment variable.
      */
-    apiKey: string;
+    apiKey?: string;
     /**
      * Base URL for the API (optional, for testing)
      * @default "https://api.oilpriceapi.com"
@@ -40,6 +41,18 @@ export interface OilPriceAPIConfig {
      * @default false
      */
     debug?: boolean;
+    /**
+     * Your application's URL (optional, for telemetry)
+     * Helps us understand how the API is being used and may unlock
+     * a 10% bonus to your request limit.
+     * @example "https://myapp.com"
+     */
+    appUrl?: string;
+    /**
+     * Your application's name (optional, for telemetry)
+     * @example "MyFuelPriceTracker"
+     */
+    appName?: string;
 }
 /**
  * Represents a single price data point
@@ -77,22 +90,22 @@ export interface Price {
      * Price changes over different time periods (24h, 7d, 30d, 90d)
      */
     changes?: {
-        '24h'?: {
+        "24h"?: {
             amount: number;
             percent: number;
             previous_price: number;
         };
-        '7d'?: {
+        "7d"?: {
             amount: number;
             percent: number;
             previous_price: number;
         };
-        '30d'?: {
+        "30d"?: {
             amount: number;
             percent: number;
             previous_price: number;
         };
-        '90d'?: {
+        "90d"?: {
             amount: number;
             percent: number;
             previous_price: number;
@@ -119,7 +132,7 @@ export interface LatestPricesOptions {
 /**
  * Time period options for historical data
  */
-export type HistoricalPeriod = 'past_week' | 'past_month' | 'past_year';
+export type HistoricalPeriod = "past_week" | "past_month" | "past_year";
 /**
  * Aggregation interval for historical data
  *
@@ -127,7 +140,7 @@ export type HistoricalPeriod = 'past_week' | 'past_month' | 'past_year';
  * response times from 74s to <1s. The 'raw' option returns individual price
  * points which can be 600k+ records for a year of BRENT data.
  */
-export type AggregationInterval = 'raw' | 'hourly' | 'daily' | 'weekly' | 'monthly';
+export type AggregationInterval = "raw" | "hourly" | "daily" | "weekly" | "monthly";
 /**
  * Options for fetching historical prices
  */
@@ -241,3 +254,61 @@ export interface CommodityCategory {
 export interface CategoriesResponse {
     [categoryKey: string]: CommodityCategory;
 }
+/**
+ * BYOS (Bring Your Own Subscription) price from Data Connector
+ */
+export interface DataConnectorPrice {
+    /**
+     * Price value in specified currency
+     */
+    price: number;
+    /**
+     * Currency code (e.g., "USD")
+     */
+    currency: string;
+    /**
+     * Fuel type (e.g., "VLSFO", "MGO", "IFO380")
+     */
+    fuel_type: string;
+    /**
+     * Port name (e.g., "SINGAPORE", "ROTTERDAM")
+     */
+    port: string;
+    /**
+     * Geographic region (AMERICAS, EMEA, APAC)
+     */
+    region: string | null;
+    /**
+     * Unit of measurement (typically "MT" for metric ton)
+     */
+    unit: string;
+    /**
+     * Data source provider (e.g., "shipandbunker")
+     */
+    source: string;
+    /**
+     * ISO 8601 timestamp when price was recorded
+     */
+    timestamp: string;
+}
+/**
+ * Options for fetching Data Connector prices
+ */
+export interface DataConnectorOptions {
+    /**
+     * Filter by fuel type (VLSFO, MGO, IFO380)
+     */
+    fuelType?: string;
+    /**
+     * Filter by port name
+     */
+    port?: string;
+    /**
+     * Filter by region (AMERICAS, EMEA, APAC)
+     */
+    region?: string;
+    /**
+     * ISO 8601 timestamp to fetch prices after
+     */
+    since?: string;
+}

package/dist/version.d.ts

@@ -7,7 +7,7 @@
  * - X-Client-Version header
  * - Package.json (should match)
  */
-export declare const SDK_VERSION = "0.6.0";
+export declare const SDK_VERSION = "0.8.2";
 /**
  * SDK identifier used in User-Agent and X-Api-Client headers
  */

package/dist/version.js

@@ -7,11 +7,11 @@
  * - X-Client-Version header
  * - Package.json (should match)
  */
-export const SDK_VERSION = '0.6.0';
+export const SDK_VERSION = "0.8.2";
 /**
  * SDK identifier used in User-Agent and X-Api-Client headers
  */
-export const SDK_NAME = 'oilpriceapi-node';
+export const SDK_NAME = "oilpriceapi-node";
 /**
  * Build the full User-Agent string
  */

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "oilpriceapi",
-  "version": "0.6.0",
+  "version": "0.8.2",
   "description": "Official Node.js SDK for Oil Price API - Real-time and historical oil & commodity prices",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     }
   },
   "files": [
@@ -18,9 +23,11 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.cjs.json && echo '{\"type\":\"commonjs\"}' > dist/cjs/package.json",
+    "lint": "eslint src/",
     "test": "vitest run",
     "test:watch": "vitest",
+    "docs": "typedoc",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -55,8 +62,10 @@
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
-    "@vitest/coverage-v8": "^1.0.0",
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "^9.39.4",
     "typescript": "^5.3.0",
-    "vitest": "^1.0.0"
+    "typescript-eslint": "^8.57.2",
+    "vitest": "^4.0.16"
   }
 }