oilpriceapi 0.6.0 → 0.8.2

package/dist/resources/storage.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Storage Resource
+ *
+ * Access crude oil storage data including total US inventory, Cushing hub levels,
+ * Strategic Petroleum Reserve (SPR), and regional breakdowns.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Storage level data
+ */
+export interface StorageData {
+    /** Storage location code */
+    code: string;
+    /** Location name */
+    name?: string;
+    /** Current storage level */
+    level: number;
+    /** Unit of measurement (typically "thousand_barrels" or "million_barrels") */
+    unit: string;
+    /** ISO timestamp when data was recorded */
+    timestamp: string;
+    /** Change from previous period */
+    change?: number;
+    /** Percentage change */
+    change_percent?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Historical storage data point
+ */
+export interface HistoricalStorageData {
+    /** Date in YYYY-MM-DD format */
+    date: string;
+    /** Storage level */
+    level: number;
+    /** Unit of measurement */
+    unit: string;
+    /** Week-over-week change */
+    change?: number;
+}
+/**
+ * Options for historical storage query
+ */
+export interface HistoricalStorageOptions {
+    /** Start date in ISO 8601 format (YYYY-MM-DD) */
+    startDate?: string;
+    /** End date in ISO 8601 format (YYYY-MM-DD) */
+    endDate?: string;
+}
+/**
+ * Storage Resource
+ *
+ * Access crude oil storage data for US inventory levels, Cushing hub,
+ * Strategic Petroleum Reserve, and regional breakdowns.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get all storage data
+ * const storage = await client.storage.all();
+ * console.log(`Total US inventory: ${storage.level} ${storage.unit}`);
+ *
+ * // Get Cushing levels
+ * const cushing = await client.storage.cushing();
+ * console.log(`Cushing: ${cushing.level} ${cushing.unit}`);
+ *
+ * // Get SPR levels
+ * const spr = await client.storage.spr();
+ * console.log(`SPR: ${spr.level} ${spr.unit}`);
+ * ```
+ */
+export declare class StorageResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * Get all current storage levels
+     *
+     * Returns total US commercial crude oil inventory.
+     *
+     * @returns Current storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const storage = await client.storage.all();
+     * console.log(`Total inventory: ${storage.level} ${storage.unit}`);
+     * if (storage.change) {
+     *   console.log(`Change: ${storage.change > 0 ? '+' : ''}${storage.change}`);
+     * }
+     * ```
+     */
+    all(): Promise<StorageData>;
+    /**
+     * Get Cushing, OK storage levels
+     *
+     * Returns current inventory at Cushing, Oklahoma - the key delivery point
+     * for WTI crude oil futures.
+     *
+     * @returns Cushing storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const cushing = await client.storage.cushing();
+     * console.log(`Cushing inventory: ${cushing.level} ${cushing.unit}`);
+     * console.log(`Week-over-week change: ${cushing.change_percent}%`);
+     * ```
+     */
+    cushing(): Promise<StorageData>;
+    /**
+     * Get Strategic Petroleum Reserve (SPR) levels
+     *
+     * Returns current US Strategic Petroleum Reserve inventory.
+     *
+     * @returns SPR storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const spr = await client.storage.spr();
+     * console.log(`SPR inventory: ${spr.level} ${spr.unit}`);
+     * ```
+     */
+    spr(): Promise<StorageData>;
+    /**
+     * Get regional storage breakdown
+     *
+     * Returns storage levels by region (PADD districts) or a specific region.
+     *
+     * @param region - Optional region code (e.g., "PADD1", "PADD2", "PADD3")
+     * @returns Regional storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * // Get all regions
+     * const regions = await client.storage.regional();
+     *
+     * // Get specific region (Gulf Coast)
+     * const gulfCoast = await client.storage.regional('PADD3');
+     * console.log(`PADD 3 (Gulf Coast): ${gulfCoast.level} ${gulfCoast.unit}`);
+     * ```
+     */
+    regional(region?: string): Promise<StorageData | StorageData[]>;
+    /**
+     * Get historical storage data
+     *
+     * Returns time series of storage levels for a specific location.
+     *
+     * @param code - Storage location code (e.g., "US", "CUSHING", "SPR")
+     * @param options - Date range filters
+     * @returns Array of historical storage data
+     *
+     * @throws {NotFoundError} If location code not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const history = await client.storage.history('CUSHING', {
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31'
+     * });
+     *
+     * history.forEach(point => {
+     *   console.log(`${point.date}: ${point.level} ${point.unit}`);
+     * });
+     * ```
+     */
+    history(code: string, options?: HistoricalStorageOptions): Promise<HistoricalStorageData[]>;
+}

package/dist/resources/storage.js

@@ -0,0 +1,162 @@
+/**
+ * Storage Resource
+ *
+ * Access crude oil storage data including total US inventory, Cushing hub levels,
+ * Strategic Petroleum Reserve (SPR), and regional breakdowns.
+ */
+import { ValidationError } from "../errors.js";
+/**
+ * Storage Resource
+ *
+ * Access crude oil storage data for US inventory levels, Cushing hub,
+ * Strategic Petroleum Reserve, and regional breakdowns.
+ *
+ * @example
+ * ```typescript
+ * import { OilPriceAPI } from 'oilpriceapi';
+ *
+ * const client = new OilPriceAPI({ apiKey: 'your_key' });
+ *
+ * // Get all storage data
+ * const storage = await client.storage.all();
+ * console.log(`Total US inventory: ${storage.level} ${storage.unit}`);
+ *
+ * // Get Cushing levels
+ * const cushing = await client.storage.cushing();
+ * console.log(`Cushing: ${cushing.level} ${cushing.unit}`);
+ *
+ * // Get SPR levels
+ * const spr = await client.storage.spr();
+ * console.log(`SPR: ${spr.level} ${spr.unit}`);
+ * ```
+ */
+export class StorageResource {
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Get all current storage levels
+     *
+     * Returns total US commercial crude oil inventory.
+     *
+     * @returns Current storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const storage = await client.storage.all();
+     * console.log(`Total inventory: ${storage.level} ${storage.unit}`);
+     * if (storage.change) {
+     *   console.log(`Change: ${storage.change > 0 ? '+' : ''}${storage.change}`);
+     * }
+     * ```
+     */
+    async all() {
+        return this.client["request"]("/v1/storage", {});
+    }
+    /**
+     * Get Cushing, OK storage levels
+     *
+     * Returns current inventory at Cushing, Oklahoma - the key delivery point
+     * for WTI crude oil futures.
+     *
+     * @returns Cushing storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const cushing = await client.storage.cushing();
+     * console.log(`Cushing inventory: ${cushing.level} ${cushing.unit}`);
+     * console.log(`Week-over-week change: ${cushing.change_percent}%`);
+     * ```
+     */
+    async cushing() {
+        return this.client["request"]("/v1/storage/cushing", {});
+    }
+    /**
+     * Get Strategic Petroleum Reserve (SPR) levels
+     *
+     * Returns current US Strategic Petroleum Reserve inventory.
+     *
+     * @returns SPR storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * const spr = await client.storage.spr();
+     * console.log(`SPR inventory: ${spr.level} ${spr.unit}`);
+     * ```
+     */
+    async spr() {
+        return this.client["request"]("/v1/storage/spr", {});
+    }
+    /**
+     * Get regional storage breakdown
+     *
+     * Returns storage levels by region (PADD districts) or a specific region.
+     *
+     * @param region - Optional region code (e.g., "PADD1", "PADD2", "PADD3")
+     * @returns Regional storage data
+     *
+     * @throws {OilPriceAPIError} If API request fails
+     * @throws {AuthenticationError} If API key is invalid
+     *
+     * @example
+     * ```typescript
+     * // Get all regions
+     * const regions = await client.storage.regional();
+     *
+     * // Get specific region (Gulf Coast)
+     * const gulfCoast = await client.storage.regional('PADD3');
+     * console.log(`PADD 3 (Gulf Coast): ${gulfCoast.level} ${gulfCoast.unit}`);
+     * ```
+     */
+    async regional(region) {
+        const params = {};
+        if (region)
+            params.region = region;
+        return this.client["request"]("/v1/storage/regional", params);
+    }
+    /**
+     * Get historical storage data
+     *
+     * Returns time series of storage levels for a specific location.
+     *
+     * @param code - Storage location code (e.g., "US", "CUSHING", "SPR")
+     * @param options - Date range filters
+     * @returns Array of historical storage data
+     *
+     * @throws {NotFoundError} If location code not found
+     * @throws {OilPriceAPIError} If API request fails
+     *
+     * @example
+     * ```typescript
+     * const history = await client.storage.history('CUSHING', {
+     *   startDate: '2024-01-01',
+     *   endDate: '2024-12-31'
+     * });
+     *
+     * history.forEach(point => {
+     *   console.log(`${point.date}: ${point.level} ${point.unit}`);
+     * });
+     * ```
+     */
+    async history(code, options) {
+        if (!code || typeof code !== "string") {
+            throw new ValidationError("Storage location code must be a non-empty string");
+        }
+        const params = {};
+        if (options?.startDate)
+            params.start_date = options.startDate;
+        if (options?.endDate)
+            params.end_date = options.endDate;
+        const response = await this.client["request"](`/v1/storage/${code}/history`, params);
+        return Array.isArray(response) ? response : response.data;
+    }
+}

package/dist/resources/webhooks.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Webhooks Resource
+ *
+ * Manage webhook endpoints for real-time event notifications.
+ */
+import type { OilPriceAPI } from "../client.js";
+/**
+ * Webhook endpoint configuration
+ */
+export interface WebhookEndpoint {
+    /** Unique webhook identifier */
+    id: string;
+    /** User-friendly webhook name */
+    name: string;
+    /** Webhook URL (must be HTTPS) */
+    url: string;
+    /** Event types to subscribe to */
+    events: string[];
+    /** Whether the webhook is active */
+    enabled: boolean;
+    /** Optional secret for signature verification */
+    secret?: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+    /** Number of successful deliveries */
+    successful_deliveries: number;
+    /** Number of failed deliveries */
+    failed_deliveries: number;
+    /** Last delivery status */
+    last_delivery_status?: "success" | "failed";
+    /** ISO timestamp of last delivery attempt */
+    last_delivery_at?: string;
+    /** ISO timestamp when webhook was created */
+    created_at: string;
+    /** ISO timestamp when webhook was last updated */
+    updated_at: string;
+}
+/**
+ * Parameters for creating a webhook
+ */
+export interface CreateWebhookParams {
+    /** User-friendly webhook name */
+    name: string;
+    /** Webhook URL (must be HTTPS) */
+    url: string;
+    /** Event types to subscribe to */
+    events: string[];
+    /** Whether to enable immediately (default: true) */
+    enabled?: boolean;
+    /** Optional secret for signature verification */
+    secret?: string;
+    /** Optional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Parameters for updating a webhook
+ */
+export interface UpdateWebhookParams {
+    /** User-friendly webhook name */
+    name?: string;
+    /** Webhook URL */
+    url?: string;
+    /** Event types to subscribe to */
+    events?: string[];
+    /** Whether the webhook is active */
+    enabled?: boolean;
+    /** Secret for signature verification */
+    secret?: string;
+    /** Metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Webhook test response
+ */
+export interface WebhookTestResponse {
+    /** Test result status */
+    success: boolean;
+    /** HTTP status code from webhook endpoint */
+    status_code: number;
+    /** Response time in milliseconds */
+    response_time_ms: number;
+    /** Response body from webhook endpoint */
+    response_body?: string;
+    /** Error message if test failed */
+    error?: string;
+}
+/**
+ * Webhook event record
+ */
+export interface WebhookEvent {
+    /** Event ID */
+    id: string;
+    /** Webhook endpoint ID */
+    webhook_id: string;
+    /** Event type */
+    event_type: string;
+    /** Event payload */
+    payload: Record<string, unknown>;
+    /** Delivery status */
+    status: "pending" | "success" | "failed";
+    /** Number of delivery attempts */
+    attempts: number;
+    /** HTTP status code from delivery */
+    status_code?: number;
+    /** Error message if delivery failed */
+    error?: string;
+    /** ISO timestamp when event was created */
+    created_at: string;
+    /** ISO timestamp of last delivery attempt */
+    delivered_at?: string;
+}
+/**
+ * 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 declare class WebhooksResource {
+    private client;
+    constructor(client: OilPriceAPI);
+    /**
+     * 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(', ')}`);
+     * });
+     * ```
+     */
+    list(): Promise<WebhookEndpoint[]>;
+    /**
+     * 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}`);
+     * ```
+     */
+    get(id: string): Promise<WebhookEndpoint>;
+    /**
+     * 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}`);
+     * ```
+     */
+    create(params: CreateWebhookParams): Promise<WebhookEndpoint>;
+    /**
+     * 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']
+     * });
+     * ```
+     */
+    update(id: string, params: UpdateWebhookParams): Promise<WebhookEndpoint>;
+    /**
+     * 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');
+     * ```
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    test(id: string): Promise<WebhookTestResponse>;
+    /**
+     * 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)`);
+     * });
+     * ```
+     */
+    events(id: string): Promise<WebhookEvent[]>;
+    /**
+     * 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: string | Buffer, signature: string, secret: string): boolean;
+}