oilpriceapi 0.6.0 → 0.8.2

package/dist/index.js

@@ -5,6 +5,43 @@
  *
  * @packageDocumentation
  */
-export { OilPriceAPI } from './client.js';
-export { SDK_VERSION, SDK_NAME } from './version.js';
-export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, TimeoutError, } from './errors.js';
+import { createHmac, timingSafeEqual } from "node:crypto";
+export { OilPriceAPI } from "./client.js";
+export { SDK_VERSION, SDK_NAME } from "./version.js";
+export { OilPriceAPIError, AuthenticationError, RateLimitError, NotFoundError, ServerError, ValidationError, TimeoutError, } from "./errors.js";
+export { DieselResource } from "./resources/diesel.js";
+export { AlertsResource } from "./resources/alerts.js";
+export { CommoditiesResource } from "./resources/commodities.js";
+export { FuturesResource } from "./resources/futures.js";
+export { StorageResource } from "./resources/storage.js";
+export { RigCountsResource } from "./resources/rig-counts.js";
+export { BunkerFuelsResource } from "./resources/bunker-fuels.js";
+export { AnalyticsResource } from "./resources/analytics.js";
+export { ForecastsResource } from "./resources/forecasts.js";
+export { DataQualityResource } from "./resources/data-quality.js";
+export { DrillingIntelligenceResource } from "./resources/drilling.js";
+export { EnergyIntelligenceResource, EIRigCountsResource, EIOilInventoriesResource, EIOPECProductionResource, EIDrillingProductivityResource, EIForecastsResource, EIWellPermitsResource, EIFracFocusResource, } from "./resources/ei/index.js";
+export { WebhooksResource } from "./resources/webhooks.js";
+export { DataSourcesResource } from "./resources/data-sources.js";
+/**
+ * Standalone webhook signature verification.
+ *
+ * Convenience function for verifying webhook signatures without
+ * instantiating a full client.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from 'oilpriceapi';
+ *
+ * const isValid = verifyWebhookSignature(rawBody, signatureHeader, secret);
+ * ```
+ */
+export function verifyWebhookSignature(payload, signature, secret) {
+    const expectedSignature = "sha256=" + createHmac("sha256", secret).update(payload).digest("hex");
+    try {
+        return timingSafeEqual(Buffer.from(expectedSignature), Buffer.from(signature));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/resources/alerts.d.ts

@@ -3,11 +3,11 @@
  *
  * Manage price alert configurations for automated notifications.
  */
-import type { OilPriceAPI } from '../client.js';
+import type { OilPriceAPI } from "../client.js";
 /**
  * Valid condition operators for price alerts
  */
-export type AlertOperator = 'greater_than' | 'less_than' | 'equals' | 'greater_than_or_equal' | 'less_than_or_equal';
+export type AlertOperator = "greater_than" | "less_than" | "equals" | "greater_than_or_equal" | "less_than_or_equal";
 /**
  * Price alert configuration
  */
@@ -275,24 +275,61 @@ export declare class AlertsResource {
      */
     delete(id: string): Promise<void>;
     /**
-     * Test a webhook endpoint
+     * Test an alert
      *
-     * **NOTE:** This feature is not yet available in the API. The `/v1/alerts/test_webhook`
-     * endpoint has not been implemented yet. This method will throw an error until the
-     * backend endpoint is added.
+     * Triggers a test run of the alert to verify it's working correctly.
+     * Does not affect the alert's cooldown or trigger count.
      *
-     * To test if an alert would trigger, use the backend's `/v1/alerts/test` endpoint instead:
-     * ```bash
-     * curl -X POST "https://api.oilpriceapi.com/v1/alerts/:id/test" \
-     *   -H "Authorization: Bearer YOUR_API_KEY"
+     * @param alertId - The alert ID to test
+     * @returns Test results
+     *
+     * @throws {NotFoundError} If alert not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.alerts.test(alertId);
+     * console.log(`Test ${result.success ? 'passed' : 'failed'}`);
+     * if (result.response_time_ms) {
+     *   console.log(`Webhook response time: ${result.response_time_ms}ms`);
+     * }
      * ```
+     */
+    test(alertId: string): Promise<WebhookTestResponse>;
+    /**
+     * Get available alert triggers
+     *
+     * Returns list of supported trigger conditions and event types.
      *
-     * @param webhookUrl - The HTTPS webhook URL to test
-     * @returns Test results including response time and status
+     * @returns Array of available triggers
      *
-     * @throws {Error} Feature not yet available
+     * @throws {OilPriceAPIError} If API request fails
      *
-     * @deprecated This feature is not yet available in the API
+     * @example
+     * ```typescript
+     * const triggers = await client.alerts.triggers();
+     * triggers.forEach(trigger => {
+     *   console.log(`${trigger.name}: ${trigger.description}`);
+     * });
+     * ```
+     */
+    triggers(): Promise<any[]>;
+    /**
+     * Get alert analytics history
+     *
+     * Returns historical analytics data for alerts including trigger frequency,
+     * success rates, and response times.
+     *
+     * @returns Analytics history data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const analytics = await client.alerts.analyticsHistory();
+     * console.log(`Total triggers: ${analytics.total_triggers}`);
+     * console.log(`Success rate: ${analytics.success_rate}%`);
+     * ```
      */
-    testWebhook(webhookUrl: string): Promise<WebhookTestResponse>;
+    analyticsHistory(): Promise<any>;
 }

package/dist/resources/alerts.js

@@ -3,6 +3,7 @@
  *
  * Manage price alert configurations for automated notifications.
  */
+import { ValidationError } from "../errors.js";
 /**
  * Price Alerts Resource
  *
@@ -76,9 +77,9 @@ export class AlertsResource {
      * ```
      */
     async list() {
-        const response = await this.client['request']('/v1/alerts', {});
+        const response = await this.client["request"]("/v1/alerts", {});
         // API returns array directly, but handle both formats for compatibility
-        return Array.isArray(response) ? response : (response.alerts || []);
+        return Array.isArray(response) ? response : response.alerts || [];
     }
     /**
      * Get a specific price alert by ID
@@ -99,12 +100,12 @@ export class AlertsResource {
      * ```
      */
     async get(id) {
-        if (!id || typeof id !== 'string') {
-            throw new Error('Alert ID must be a non-empty string');
+        if (!id || typeof id !== "string") {
+            throw new ValidationError("Alert ID must be a non-empty string");
         }
-        const response = await this.client['request'](`/v1/alerts/${id}`, {});
+        const response = await this.client["request"](`/v1/alerts/${id}`, {});
         // API returns object directly, but handle both formats for compatibility
-        return 'alert' in response ? response.alert : response;
+        return "alert" in response ? response.alert : response;
     }
     /**
      * Create a new price alert
@@ -145,59 +146,54 @@ export class AlertsResource {
      */
     async create(params) {
         // Validate required fields
-        if (!params.name || typeof params.name !== 'string') {
-            throw new Error('Alert name is required and must be a string');
+        if (!params.name || typeof params.name !== "string") {
+            throw new ValidationError("Alert name is required and must be a string");
         }
         if (params.name.length < 1 || params.name.length > 100) {
-            throw new Error('Alert name must be 1-100 characters');
+            throw new ValidationError("Alert name must be 1-100 characters");
         }
-        if (!params.commodity_code || typeof params.commodity_code !== 'string') {
-            throw new Error('Commodity code is required and must be a string');
+        if (!params.commodity_code || typeof params.commodity_code !== "string") {
+            throw new ValidationError("Commodity code is required and must be a string");
         }
         if (!params.condition_operator) {
-            throw new Error('Condition operator is required');
+            throw new ValidationError("Condition operator is required");
         }
         const validOperators = [
-            'greater_than',
-            'less_than',
-            'equals',
-            'greater_than_or_equal',
-            'less_than_or_equal'
+            "greater_than",
+            "less_than",
+            "equals",
+            "greater_than_or_equal",
+            "less_than_or_equal",
         ];
         if (!validOperators.includes(params.condition_operator)) {
-            throw new Error(`Invalid operator. Must be one of: ${validOperators.join(', ')}`);
+            throw new ValidationError(`Invalid operator. Must be one of: ${validOperators.join(", ")}`);
         }
-        if (typeof params.condition_value !== 'number') {
-            throw new Error('Condition value must be a number');
+        if (typeof params.condition_value !== "number") {
+            throw new ValidationError("Condition value must be a number");
         }
         if (params.condition_value <= 0 || params.condition_value > 1000000) {
-            throw new Error('Condition value must be greater than 0 and less than or equal to 1,000,000');
+            throw new ValidationError("Condition value must be greater than 0 and less than or equal to 1,000,000");
         }
         // Validate optional fields
         if (params.webhook_url !== undefined) {
-            if (typeof params.webhook_url !== 'string') {
-                throw new Error('Webhook URL must be a string');
+            if (typeof params.webhook_url !== "string") {
+                throw new ValidationError("Webhook URL must be a string");
             }
-            if (params.webhook_url && !params.webhook_url.startsWith('https://')) {
-                throw new Error('Webhook URL must use HTTPS protocol');
+            if (params.webhook_url && !params.webhook_url.startsWith("https://")) {
+                throw new ValidationError("Webhook URL must use HTTPS protocol");
             }
         }
         if (params.cooldown_minutes !== undefined) {
-            if (typeof params.cooldown_minutes !== 'number') {
-                throw new Error('Cooldown minutes must be a number');
+            if (typeof params.cooldown_minutes !== "number") {
+                throw new ValidationError("Cooldown minutes must be a number");
             }
             if (params.cooldown_minutes < 0 || params.cooldown_minutes > 1440) {
-                throw new Error('Cooldown minutes must be between 0 and 1440 (24 hours)');
+                throw new ValidationError("Cooldown minutes must be between 0 and 1440 (24 hours)");
             }
         }
-        const url = `${this.client['baseUrl']}/v1/alerts`;
-        const response = await fetch(url, {
-            method: 'POST',
-            headers: {
-                'Authorization': `Bearer ${this.client['apiKey']}`,
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({
+        const response = await this.client["request"]("/v1/alerts", {}, {
+            method: "POST",
+            body: {
                 price_alert: {
                     name: params.name,
                     commodity_code: params.commodity_code,
@@ -206,17 +202,11 @@ export class AlertsResource {
                     webhook_url: params.webhook_url,
                     enabled: params.enabled ?? true,
                     cooldown_minutes: params.cooldown_minutes ?? 60,
-                    metadata: params.metadata
-                }
-            })
+                    metadata: params.metadata,
+                },
+            },
         });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to create alert: ${response.status} ${errorText}`);
-        }
-        const data = await response.json();
-        // API returns object directly, but handle both formats for compatibility
-        return 'alert' in data ? data.alert : data;
+        return "alert" in response ? response.alert : response;
     }
     /**
      * Update an existing price alert
@@ -250,65 +240,55 @@ export class AlertsResource {
      * ```
      */
     async update(id, params) {
-        if (!id || typeof id !== 'string') {
-            throw new Error('Alert ID must be a non-empty string');
+        if (!id || typeof id !== "string") {
+            throw new ValidationError("Alert ID must be a non-empty string");
         }
         // Validate fields if provided
         if (params.name !== undefined) {
-            if (typeof params.name !== 'string' || params.name.length < 1 || params.name.length > 100) {
-                throw new Error('Alert name must be 1-100 characters');
+            if (typeof params.name !== "string" ||
+                params.name.length < 1 ||
+                params.name.length > 100) {
+                throw new ValidationError("Alert name must be 1-100 characters");
             }
         }
         if (params.condition_operator !== undefined) {
             const validOperators = [
-                'greater_than',
-                'less_than',
-                'equals',
-                'greater_than_or_equal',
-                'less_than_or_equal'
+                "greater_than",
+                "less_than",
+                "equals",
+                "greater_than_or_equal",
+                "less_than_or_equal",
             ];
             if (!validOperators.includes(params.condition_operator)) {
-                throw new Error(`Invalid operator. Must be one of: ${validOperators.join(', ')}`);
+                throw new ValidationError(`Invalid operator. Must be one of: ${validOperators.join(", ")}`);
             }
         }
         if (params.condition_value !== undefined) {
-            if (typeof params.condition_value !== 'number') {
-                throw new Error('Condition value must be a number');
+            if (typeof params.condition_value !== "number") {
+                throw new ValidationError("Condition value must be a number");
             }
             if (params.condition_value <= 0 || params.condition_value > 1000000) {
-                throw new Error('Condition value must be greater than 0 and less than or equal to 1,000,000');
+                throw new ValidationError("Condition value must be greater than 0 and less than or equal to 1,000,000");
             }
         }
         if (params.webhook_url !== undefined && params.webhook_url !== null) {
-            if (typeof params.webhook_url !== 'string' || !params.webhook_url.startsWith('https://')) {
-                throw new Error('Webhook URL must be a valid HTTPS URL');
+            if (typeof params.webhook_url !== "string" ||
+                !params.webhook_url.startsWith("https://")) {
+                throw new ValidationError("Webhook URL must be a valid HTTPS URL");
             }
         }
         if (params.cooldown_minutes !== undefined) {
-            if (typeof params.cooldown_minutes !== 'number' ||
+            if (typeof params.cooldown_minutes !== "number" ||
                 params.cooldown_minutes < 0 ||
                 params.cooldown_minutes > 1440) {
-                throw new Error('Cooldown minutes must be between 0 and 1440 (24 hours)');
+                throw new ValidationError("Cooldown minutes must be between 0 and 1440 (24 hours)");
             }
         }
-        const url = `${this.client['baseUrl']}/v1/alerts/${id}`;
-        const response = await fetch(url, {
-            method: 'PATCH',
-            headers: {
-                'Authorization': `Bearer ${this.client['apiKey']}`,
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({
-                price_alert: params
-            })
+        const response = await this.client["request"](`/v1/alerts/${id}`, {}, {
+            method: "PATCH",
+            body: { price_alert: params },
         });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to update alert: ${response.status} ${errorText}`);
-        }
-        const data = await response.json();
-        // API returns object directly, but handle both formats for compatibility
-        return 'alert' in data ? data.alert : data;
+        return "alert" in response ? response.alert : response;
     }
     /**
      * Delete a price alert
@@ -327,45 +307,77 @@ export class AlertsResource {
      * ```
      */
     async delete(id) {
-        if (!id || typeof id !== 'string') {
-            throw new Error('Alert ID must be a non-empty string');
+        if (!id || typeof id !== "string") {
+            throw new ValidationError("Alert ID must be a non-empty string");
         }
-        const url = `${this.client['baseUrl']}/v1/alerts/${id}`;
-        const response = await fetch(url, {
-            method: 'DELETE',
-            headers: {
-                'Authorization': `Bearer ${this.client['apiKey']}`,
-                'Content-Type': 'application/json',
-            }
-        });
-        if (!response.ok) {
-            const errorText = await response.text();
-            throw new Error(`Failed to delete alert: ${response.status} ${errorText}`);
+        await this.client["request"](`/v1/alerts/${id}`, {}, { method: "DELETE" });
+    }
+    /**
+     * Test an alert
+     *
+     * Triggers a test run of the alert to verify it's working correctly.
+     * Does not affect the alert's cooldown or trigger count.
+     *
+     * @param alertId - The alert ID to test
+     * @returns Test results
+     *
+     * @throws {NotFoundError} If alert not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const result = await client.alerts.test(alertId);
+     * console.log(`Test ${result.success ? 'passed' : 'failed'}`);
+     * if (result.response_time_ms) {
+     *   console.log(`Webhook response time: ${result.response_time_ms}ms`);
+     * }
+     * ```
+     */
+    async test(alertId) {
+        if (!alertId || typeof alertId !== "string") {
+            throw new ValidationError("Alert ID must be a non-empty string");
         }
+        return this.client["request"](`/v1/alerts/${alertId}/test`, {}, { method: "POST" });
     }
     /**
-     * Test a webhook endpoint
+     * Get available alert triggers
      *
-     * **NOTE:** This feature is not yet available in the API. The `/v1/alerts/test_webhook`
-     * endpoint has not been implemented yet. This method will throw an error until the
-     * backend endpoint is added.
+     * Returns list of supported trigger conditions and event types.
      *
-     * To test if an alert would trigger, use the backend's `/v1/alerts/test` endpoint instead:
-     * ```bash
-     * curl -X POST "https://api.oilpriceapi.com/v1/alerts/:id/test" \
-     *   -H "Authorization: Bearer YOUR_API_KEY"
+     * @returns Array of available triggers
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const triggers = await client.alerts.triggers();
+     * triggers.forEach(trigger => {
+     *   console.log(`${trigger.name}: ${trigger.description}`);
+     * });
      * ```
+     */
+    async triggers() {
+        const response = await this.client["request"]("/v1/alerts/triggers", {});
+        return Array.isArray(response) ? response : response.triggers;
+    }
+    /**
+     * Get alert analytics history
+     *
+     * Returns historical analytics data for alerts including trigger frequency,
+     * success rates, and response times.
      *
-     * @param webhookUrl - The HTTPS webhook URL to test
-     * @returns Test results including response time and status
+     * @returns Analytics history data
      *
-     * @throws {Error} Feature not yet available
+     * @throws {OilPriceAPIError} If API request fails
      *
-     * @deprecated This feature is not yet available in the API
+     * @example
+     * ```typescript
+     * const analytics = await client.alerts.analyticsHistory();
+     * console.log(`Total triggers: ${analytics.total_triggers}`);
+     * console.log(`Success rate: ${analytics.success_rate}%`);
+     * ```
      */
-    async testWebhook(webhookUrl) {
-        throw new Error('Webhook testing is not yet available. The /v1/alerts/test_webhook endpoint ' +
-            'has not been implemented in the API. To test if an alert would trigger, ' +
-            'use the /v1/alerts/:id/test endpoint instead.');
+    async analyticsHistory() {
+        return this.client["request"]("/v1/alerts/analytics_history", {});
     }
 }