@drip-sdk/node 1.0.10 → 1.1.0

package/dist/index.d.ts

@@ -140,6 +140,327 @@ declare class StreamMeter {
     reset(): void;
 }
 
+/**
+ * Production-grade resilience patterns for the Drip SDK.
+ *
+ * This module provides:
+ * - Rate limiting (token bucket algorithm)
+ * - Retry with exponential backoff
+ * - Circuit breaker pattern
+ * - Request metrics and observability
+ */
+/**
+ * Configuration for rate limiting.
+ */
+interface RateLimiterConfig {
+    /**
+     * Maximum requests per second.
+     * @default 100
+     */
+    requestsPerSecond: number;
+    /**
+     * Maximum burst size (bucket capacity).
+     * @default 200
+     */
+    burstSize: number;
+    /**
+     * Whether rate limiting is enabled.
+     * @default true
+     */
+    enabled: boolean;
+}
+/**
+ * Thread-safe token bucket rate limiter.
+ *
+ * Allows bursting up to `burstSize` requests, then limits to
+ * `requestsPerSecond` sustained rate.
+ */
+declare class RateLimiter {
+    private readonly config;
+    private tokens;
+    private lastRefill;
+    constructor(config?: Partial<RateLimiterConfig>);
+    /**
+     * Refill tokens based on elapsed time.
+     */
+    private refill;
+    /**
+     * Acquire a token, blocking if necessary.
+     *
+     * @param timeout - Maximum time to wait for a token in ms (undefined = wait forever)
+     * @returns Promise that resolves to true if token acquired, false if timeout
+     */
+    acquire(timeout?: number): Promise<boolean>;
+    /**
+     * Try to acquire a token without waiting.
+     *
+     * @returns true if token acquired, false otherwise
+     */
+    tryAcquire(): boolean;
+    /**
+     * Get current number of available tokens.
+     */
+    get availableTokens(): number;
+    private sleep;
+}
+/**
+ * Configuration for retry behavior.
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts.
+     * @default 3
+     */
+    maxRetries: number;
+    /**
+     * Base delay in milliseconds.
+     * @default 100
+     */
+    baseDelayMs: number;
+    /**
+     * Maximum delay in milliseconds.
+     * @default 10000
+     */
+    maxDelayMs: number;
+    /**
+     * Exponential backoff base.
+     * @default 2
+     */
+    exponentialBase: number;
+    /**
+     * Random jitter factor (0-1).
+     * @default 0.1
+     */
+    jitter: number;
+    /**
+     * HTTP status codes that should trigger retry.
+     * @default [429, 500, 502, 503, 504]
+     */
+    retryableStatusCodes: number[];
+    /**
+     * Whether retry is enabled.
+     * @default true
+     */
+    enabled: boolean;
+}
+/**
+ * Error thrown when all retry attempts have been exhausted.
+ */
+declare class RetryExhaustedError extends Error {
+    readonly attempts: number;
+    readonly lastError: Error;
+    constructor(attempts: number, lastError: Error);
+}
+/**
+ * Calculate backoff delay for a given attempt.
+ */
+declare function calculateBackoff(attempt: number, config: RetryConfig): number;
+/**
+ * Check if an error is retryable based on configuration.
+ */
+declare function isRetryableError(error: unknown, config: RetryConfig): boolean;
+/**
+ * Circuit breaker states.
+ */
+type CircuitState = 'closed' | 'open' | 'half_open';
+/**
+ * Configuration for circuit breaker.
+ */
+interface CircuitBreakerConfig {
+    /**
+     * Number of failures before opening circuit.
+     * @default 5
+     */
+    failureThreshold: number;
+    /**
+     * Number of successes in half-open to close circuit.
+     * @default 2
+     */
+    successThreshold: number;
+    /**
+     * Milliseconds to wait before transitioning from open to half-open.
+     * @default 30000
+     */
+    timeoutMs: number;
+    /**
+     * Whether circuit breaker is enabled.
+     * @default true
+     */
+    enabled: boolean;
+}
+/**
+ * Error thrown when circuit breaker is open.
+ */
+declare class CircuitBreakerOpenError extends Error {
+    readonly circuitName: string;
+    readonly timeUntilRetryMs: number;
+    constructor(circuitName: string, timeUntilRetryMs: number);
+}
+/**
+ * Circuit breaker pattern implementation.
+ *
+ * Prevents cascading failures by failing fast when a service is unhealthy.
+ */
+declare class CircuitBreaker {
+    readonly name: string;
+    private readonly config;
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureTime;
+    constructor(name: string, config?: Partial<CircuitBreakerConfig>);
+    /**
+     * Get current circuit state.
+     */
+    getState(): CircuitState;
+    /**
+     * Check if state should transition based on timeout.
+     */
+    private checkStateTransition;
+    /**
+     * Record a successful call.
+     */
+    recordSuccess(): void;
+    /**
+     * Record a failed call.
+     */
+    recordFailure(): void;
+    /**
+     * Check if a request should be allowed.
+     */
+    allowRequest(): boolean;
+    /**
+     * Get milliseconds until circuit transitions to half-open.
+     */
+    getTimeUntilRetry(): number;
+    /**
+     * Reset the circuit breaker to initial state.
+     */
+    reset(): void;
+}
+/**
+ * Metrics for a single request.
+ */
+interface RequestMetrics {
+    method: string;
+    endpoint: string;
+    statusCode: number | null;
+    durationMs: number;
+    success: boolean;
+    timestamp: number;
+    error?: string;
+    retryCount: number;
+}
+/**
+ * Aggregated metrics summary.
+ */
+interface MetricsSummary {
+    windowSize: number;
+    totalRequests: number;
+    totalSuccesses: number;
+    totalFailures: number;
+    successRate: number;
+    avgLatencyMs: number;
+    minLatencyMs: number;
+    maxLatencyMs: number;
+    p50LatencyMs: number;
+    p95LatencyMs: number;
+    p99LatencyMs: number;
+    requestsByEndpoint: Record<string, number>;
+    errorsByType: Record<string, number>;
+}
+/**
+ * Collects and aggregates request metrics.
+ *
+ * Thread-safe metrics collection with windowed aggregation.
+ */
+declare class MetricsCollector {
+    private readonly windowSize;
+    private readonly metrics;
+    private totalRequests;
+    private totalSuccesses;
+    private totalFailures;
+    constructor(windowSize?: number);
+    /**
+     * Record a request's metrics.
+     */
+    record(metrics: RequestMetrics): void;
+    /**
+     * Get aggregated metrics summary.
+     */
+    getSummary(): MetricsSummary;
+    /**
+     * Reset all metrics.
+     */
+    reset(): void;
+}
+/**
+ * Combined configuration for all resilience features.
+ */
+interface ResilienceConfig {
+    rateLimiter: RateLimiterConfig;
+    retry: RetryConfig;
+    circuitBreaker: CircuitBreakerConfig;
+    collectMetrics: boolean;
+}
+/**
+ * Create default production configuration.
+ */
+declare function createDefaultResilienceConfig(): ResilienceConfig;
+/**
+ * Create configuration with all features disabled.
+ */
+declare function createDisabledResilienceConfig(): ResilienceConfig;
+/**
+ * Create configuration optimized for high throughput.
+ */
+declare function createHighThroughputResilienceConfig(): ResilienceConfig;
+/**
+ * Health status of resilience components.
+ */
+interface ResilienceHealth {
+    circuitBreaker: {
+        state: CircuitState;
+        timeUntilRetryMs: number;
+    };
+    rateLimiter: {
+        availableTokens: number;
+        requestsPerSecond: number;
+    };
+    metrics: MetricsSummary | null;
+}
+/**
+ * Manages all resilience features for the SDK.
+ *
+ * Provides a unified interface for rate limiting, retry, circuit breaker,
+ * and metrics collection.
+ */
+declare class ResilienceManager {
+    readonly config: ResilienceConfig;
+    readonly rateLimiter: RateLimiter;
+    readonly circuitBreaker: CircuitBreaker;
+    readonly metrics: MetricsCollector | null;
+    constructor(config?: Partial<ResilienceConfig>);
+    /**
+     * Execute a function with all resilience features.
+     *
+     * @param fn - The function to execute
+     * @param method - HTTP method for metrics
+     * @param endpoint - Endpoint for metrics
+     * @returns Result of the function
+     */
+    execute<T>(fn: () => Promise<T>, method?: string, endpoint?: string): Promise<T>;
+    /**
+     * Get current metrics summary.
+     */
+    getMetrics(): MetricsSummary | null;
+    /**
+     * Get health status of all resilience components.
+     */
+    getHealth(): ResilienceHealth;
+    private sleep;
+}
+
 /**
  * Drip SDK - Usage-based billing for Node.js
  *
@@ -195,6 +516,36 @@ interface DripConfig {
      * @default 30000
      */
     timeout?: number;
+    /**
+     * Enable production resilience features (rate limiting, retry with backoff,
+     * circuit breaker, metrics).
+     *
+     * - `true`: Use default production settings (100 req/s, 3 retries)
+     * - `'high-throughput'`: Optimized for high throughput (1000 req/s, 2 retries)
+     * - `ResilienceConfig`: Custom configuration object
+     * - `undefined`/`false`: Disabled (default for backward compatibility)
+     *
+     * @example
+     * ```typescript
+     * // Enable with defaults
+     * const drip = new Drip({ apiKey: '...', resilience: true });
+     *
+     * // High throughput mode
+     * const drip = new Drip({ apiKey: '...', resilience: 'high-throughput' });
+     *
+     * // Custom config
+     * const drip = new Drip({
+     *   apiKey: '...',
+     *   resilience: {
+     *     rateLimiter: { requestsPerSecond: 500, burstSize: 1000, enabled: true },
+     *     retry: { maxRetries: 5, enabled: true },
+     *     circuitBreaker: { failureThreshold: 10, enabled: true },
+     *     collectMetrics: true,
+     *   },
+     * });
+     * ```
+     */
+    resilience?: boolean | 'high-throughput' | Partial<ResilienceConfig>;
 }
 /**
  * Parameters for creating a new customer.
@@ -221,8 +572,8 @@ interface CreateCustomerParams {
 interface Customer {
     /** Unique customer ID in Drip */
     id: string;
-    /** Your business ID */
-    businessId: string;
+    /** Your business ID (optional - may not be returned by all endpoints) */
+    businessId?: string;
     /** Your external customer ID (if provided) */
     externalCustomerId: string | null;
     /** Customer's on-chain address */
@@ -722,6 +1073,96 @@ interface ListMetersResponse {
     /** Total count */
     count: number;
 }
+/**
+ * Custom pricing map for cost estimation.
+ * Maps usage type to unit price (e.g., { "api_call": "0.005", "token": "0.0001" })
+ */
+type CustomPricing = Record<string, string>;
+/**
+ * Parameters for estimating costs from historical usage events.
+ */
+interface EstimateFromUsageParams {
+    /** Filter to a specific customer (optional) */
+    customerId?: string;
+    /** Start of the period to estimate */
+    periodStart: Date | string;
+    /** End of the period to estimate */
+    periodEnd: Date | string;
+    /** Default price for usage types without pricing plans */
+    defaultUnitPrice?: string;
+    /** Include events that already have charges (default: true) */
+    includeChargedEvents?: boolean;
+    /** Filter to specific usage types */
+    usageTypes?: string[];
+    /** Custom pricing overrides (takes precedence over DB pricing) */
+    customPricing?: CustomPricing;
+}
+/**
+ * A usage item for hypothetical cost estimation.
+ */
+interface HypotheticalUsageItem {
+    /** The usage type (e.g., "api_call", "token") */
+    usageType: string;
+    /** The quantity of usage */
+    quantity: number;
+    /** Override unit price for this specific item */
+    unitPriceOverride?: string;
+}
+/**
+ * Parameters for estimating costs from hypothetical usage.
+ */
+interface EstimateFromHypotheticalParams {
+    /** List of usage items to estimate */
+    items: HypotheticalUsageItem[];
+    /** Default price for usage types without pricing plans */
+    defaultUnitPrice?: string;
+    /** Custom pricing overrides (takes precedence over DB pricing) */
+    customPricing?: CustomPricing;
+}
+/**
+ * A line item in the cost estimate.
+ */
+interface CostEstimateLineItem {
+    /** The usage type */
+    usageType: string;
+    /** Total quantity */
+    quantity: string;
+    /** Unit price used */
+    unitPrice: string;
+    /** Estimated cost in USDC */
+    estimatedCostUsdc: string;
+    /** Number of events (for usage-based estimates) */
+    eventCount?: number;
+    /** Whether a pricing plan was found for this usage type */
+    hasPricingPlan: boolean;
+}
+/**
+ * Response from cost estimation.
+ */
+interface CostEstimateResponse {
+    /** Business ID (optional - may not be returned by all endpoints) */
+    businessId?: string;
+    /** Customer ID (if filtered) */
+    customerId?: string;
+    /** Period start (for usage-based estimates) */
+    periodStart?: string;
+    /** Period end (for usage-based estimates) */
+    periodEnd?: string;
+    /** Breakdown by usage type */
+    lineItems: CostEstimateLineItem[];
+    /** Subtotal in USDC */
+    subtotalUsdc: string;
+    /** Total estimated cost in USDC */
+    estimatedTotalUsdc: string;
+    /** Currency (always USDC) */
+    currency: 'USDC';
+    /** Indicates this is an estimate, not a charge */
+    isEstimate: true;
+    /** When the estimate was generated */
+    generatedAt: string;
+    /** Notes about the estimate (e.g., missing pricing plans, custom pricing applied) */
+    notes: string[];
+}
 /**
  * A single event to record in a run.
  */
@@ -934,6 +1375,7 @@ declare class Drip {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly timeout;
+    private readonly resilience;
     /**
      * Creates a new Drip SDK client.
      *
@@ -942,8 +1384,21 @@ declare class Drip {
      *
      * @example
      * ```typescript
+     * // Basic usage
+     * const drip = new Drip({
+     *   apiKey: 'drip_live_abc123...',
+     * });
+     *
+     * // With production resilience (recommended)
      * const drip = new Drip({
      *   apiKey: 'drip_live_abc123...',
+     *   resilience: true,
+     * });
+     *
+     * // High throughput mode
+     * const drip = new Drip({
+     *   apiKey: 'drip_live_abc123...',
+     *   resilience: 'high-throughput',
      * });
      * ```
      */
@@ -953,6 +1408,11 @@ declare class Drip {
      * @internal
      */
     private request;
+    /**
+     * Execute the actual HTTP request (internal).
+     * @internal
+     */
+    private rawRequest;
     /**
      * Pings the Drip API to check connectivity and measure latency.
      *
@@ -973,6 +1433,45 @@ declare class Drip {
         latencyMs: number;
         timestamp: number;
     }>;
+    /**
+     * Get SDK metrics (requires resilience to be enabled).
+     *
+     * Returns aggregated metrics including success rates, latencies, and errors.
+     *
+     * @returns Metrics summary or null if resilience is not enabled
+     *
+     * @example
+     * ```typescript
+     * const drip = new Drip({ apiKey: '...', resilience: true });
+     * // ... make some requests ...
+     *
+     * const metrics = drip.getMetrics();
+     * if (metrics) {
+     *   console.log(`Success rate: ${metrics.successRate.toFixed(1)}%`);
+     *   console.log(`P95 latency: ${metrics.p95LatencyMs.toFixed(0)}ms`);
+     * }
+     * ```
+     */
+    getMetrics(): MetricsSummary | null;
+    /**
+     * Get SDK health status (requires resilience to be enabled).
+     *
+     * Returns health status including circuit breaker state and rate limiter status.
+     *
+     * @returns Health status or null if resilience is not enabled
+     *
+     * @example
+     * ```typescript
+     * const drip = new Drip({ apiKey: '...', resilience: true });
+     *
+     * const health = drip.getHealth();
+     * if (health) {
+     *   console.log(`Circuit: ${health.circuitBreaker.state}`);
+     *   console.log(`Available tokens: ${health.rateLimiter.availableTokens}`);
+     * }
+     * ```
+     */
+    getHealth(): ResilienceHealth | null;
     /**
      * Creates a new customer in your Drip account.
      *
@@ -1540,6 +2039,82 @@ declare class Drip {
      * ```
      */
     listMeters(): Promise<ListMetersResponse>;
+    /**
+     * Estimates costs from historical usage events.
+     *
+     * Use this to preview what existing usage would cost before creating charges,
+     * or to run "what-if" scenarios with custom pricing.
+     *
+     * @param params - Parameters for the estimate
+     * @returns Cost estimate with line item breakdown
+     *
+     * @example
+     * ```typescript
+     * // Estimate costs for last month's usage
+     * const estimate = await drip.estimateFromUsage({
+     *   periodStart: new Date('2024-01-01'),
+     *   periodEnd: new Date('2024-01-31'),
+     * });
+     *
+     * console.log(`Estimated total: $${estimate.estimatedTotalUsdc}`);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // "What-if" scenario with custom pricing
+     * const estimate = await drip.estimateFromUsage({
+     *   periodStart: new Date('2024-01-01'),
+     *   periodEnd: new Date('2024-01-31'),
+     *   customPricing: {
+     *     'api_call': '0.005',  // What if we charged $0.005 per call?
+     *     'token': '0.0001',    // What if we charged $0.0001 per token?
+     *   },
+     * });
+     * ```
+     */
+    estimateFromUsage(params: EstimateFromUsageParams): Promise<CostEstimateResponse>;
+    /**
+     * Estimates costs from hypothetical usage.
+     *
+     * Use this for "what-if" scenarios, budget planning, or to preview
+     * costs before usage occurs.
+     *
+     * @param params - Parameters for the estimate
+     * @returns Cost estimate with line item breakdown
+     *
+     * @example
+     * ```typescript
+     * // Estimate what 10,000 API calls and 1M tokens would cost
+     * const estimate = await drip.estimateFromHypothetical({
+     *   items: [
+     *     { usageType: 'api_call', quantity: 10000 },
+     *     { usageType: 'token', quantity: 1000000 },
+     *   ],
+     * });
+     *
+     * console.log(`Estimated total: $${estimate.estimatedTotalUsdc}`);
+     * for (const item of estimate.lineItems) {
+     *   console.log(`  ${item.usageType}: ${item.quantity} × $${item.unitPrice} = $${item.estimatedCostUsdc}`);
+     * }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Compare different pricing scenarios
+     * const currentPricing = await drip.estimateFromHypothetical({
+     *   items: [{ usageType: 'api_call', quantity: 100000 }],
+     * });
+     *
+     * const newPricing = await drip.estimateFromHypothetical({
+     *   items: [{ usageType: 'api_call', quantity: 100000 }],
+     *   customPricing: { 'api_call': '0.0005' },  // 50% discount
+     * });
+     *
+     * console.log(`Current: $${currentPricing.estimatedTotalUsdc}`);
+     * console.log(`With 50% discount: $${newPricing.estimatedTotalUsdc}`);
+     * ```
+     */
+    estimateFromHypothetical(params: EstimateFromHypotheticalParams): Promise<CostEstimateResponse>;
     /**
      * Records a complete agent run in a single call.
      *
@@ -1751,4 +2326,4 @@ declare class Drip {
     createStreamMeter(options: StreamMeterOptions): StreamMeter;
 }
 
-export { type BalanceResult, type Charge, type ChargeParams, type ChargeResult, type ChargeStatus, type CheckoutParams, type CheckoutResult, type CreateCustomerParams, type CreateWebhookParams, type CreateWebhookResponse, type CreateWorkflowParams, type Customer, type DeleteWebhookResponse, Drip, type DripConfig, DripError, type EmitEventParams, type EndRunParams, type EventResult, type ListChargesOptions, type ListChargesResponse, type ListCustomersOptions, type ListCustomersResponse, type ListMetersResponse, type ListWebhooksResponse, type Meter, type RecordRunEvent, type RecordRunParams, type RecordRunResult, type RetryOptions, type RunResult, type RunStatus, type RunTimeline, type StartRunParams, StreamMeter, type StreamMeterFlushResult, type StreamMeterOptions, type TrackUsageParams, type TrackUsageResult, type Webhook, type WebhookEventType, type Workflow, type WrapApiCallParams, type WrapApiCallResult, Drip as default };
+export { type BalanceResult, type Charge, type ChargeParams, type ChargeResult, type ChargeStatus, type CheckoutParams, type CheckoutResult, CircuitBreaker, type CircuitBreakerConfig, CircuitBreakerOpenError, type CircuitState, type CostEstimateLineItem, type CostEstimateResponse, type CreateCustomerParams, type CreateWebhookParams, type CreateWebhookResponse, type CreateWorkflowParams, type CustomPricing, type Customer, type DeleteWebhookResponse, Drip, type DripConfig, DripError, type EmitEventParams, type EndRunParams, type EstimateFromHypotheticalParams, type EstimateFromUsageParams, type EventResult, type HypotheticalUsageItem, type ListChargesOptions, type ListChargesResponse, type ListCustomersOptions, type ListCustomersResponse, type ListMetersResponse, type ListWebhooksResponse, type Meter, MetricsCollector, type MetricsSummary, RateLimiter, type RateLimiterConfig, type RecordRunEvent, type RecordRunParams, type RecordRunResult, type RequestMetrics, type ResilienceConfig, type ResilienceHealth, ResilienceManager, type RetryConfig, RetryExhaustedError, type RetryOptions, type RunResult, type RunStatus, type RunTimeline, type StartRunParams, StreamMeter, type StreamMeterFlushResult, type StreamMeterOptions, type TrackUsageParams, type TrackUsageResult, type Webhook, type WebhookEventType, type Workflow, type WrapApiCallParams, type WrapApiCallResult, calculateBackoff, createDefaultResilienceConfig, createDisabledResilienceConfig, createHighThroughputResilienceConfig, Drip as default, isRetryableError };