@drip-sdk/node 1.1.0 → 1.1.2

package/dist/index.d.cts

@@ -68,7 +68,7 @@ interface StreamMeterFlushResult {
     /** The charge result from the API (if quantity > 0) */
     charge: ChargeResult['charge'] | null;
     /** Whether this was an idempotent replay */
-    isReplay: boolean;
+    isDuplicate: boolean;
 }
 /**
  * Internal charge function type (injected by Drip class).
@@ -498,17 +498,29 @@ interface RetryOptions {
 }
 /**
  * Configuration options for the Drip SDK client.
+ *
+ * All fields are optional - the SDK will read from environment variables:
+ * - `DRIP_API_KEY` - Your Drip API key
+ * - `DRIP_BASE_URL` - Override API base URL (optional)
  */
 interface DripConfig {
     /**
      * Your Drip API key. Obtain this from the Drip dashboard.
-     * @example "drip_live_abc123..."
+     * Falls back to `DRIP_API_KEY` environment variable if not provided.
+     *
+     * Supports both key types:
+     * - **Secret keys** (`sk_live_...` / `sk_test_...`): Full access to all endpoints
+     * - **Public keys** (`pk_live_...` / `pk_test_...`): Safe for client-side use.
+     *   Can access usage, customers, charges, sessions, analytics, etc.
+     *   Cannot access webhook management, API key management, or feature flags.
+     *
+     * @example "sk_live_abc123..." or "pk_live_abc123..."
      */
-    apiKey: string;
+    apiKey?: string;
     /**
      * Base URL for the Drip API. Defaults to production API.
-     * Override for staging/development environments.
-     * @default "https://api.drip.dev/v1"
+     * Falls back to `DRIP_BASE_URL` environment variable if not provided.
+     * @default "https://drip-app-hlunj.ondigitalocean.app/v1"
      */
     baseUrl?: string;
     /**
@@ -553,14 +565,21 @@ interface DripConfig {
 interface CreateCustomerParams {
     /**
      * Your internal customer/user ID for reconciliation.
+     * At least one of `externalCustomerId` or `onchainAddress` is required.
      * @example "user_12345"
      */
     externalCustomerId?: string;
     /**
      * The customer's Drip Smart Account address (derived from their EOA).
+     * At least one of `externalCustomerId` or `onchainAddress` is required.
      * @example "0x1234567890abcdef..."
      */
-    onchainAddress: string;
+    onchainAddress?: string;
+    /**
+     * Whether this customer is internal-only (usage tracked but not billed).
+     * @default false
+     */
+    isInternal?: boolean;
     /**
      * Additional metadata to store with the customer.
      */
@@ -576,8 +595,12 @@ interface Customer {
     businessId?: string;
     /** Your external customer ID (if provided) */
     externalCustomerId: string | null;
-    /** Customer's on-chain address */
-    onchainAddress: string;
+    /** Customer's on-chain address (null for internal-only customers) */
+    onchainAddress: string | null;
+    /** Whether this customer is internal-only (usage tracked but not billed) */
+    isInternal: boolean;
+    /** Customer status */
+    status: 'ACTIVE' | 'LOW_BALANCE' | 'PAUSED';
     /** Custom metadata */
     metadata: Record<string, unknown> | null;
     /** ISO timestamp of creation */
@@ -645,8 +668,8 @@ interface ChargeParams {
      */
     quantity: number;
     /**
-     * Unique key to prevent duplicate charges.
-     * If provided, retrying with the same key returns the original charge.
+     * Unique key to prevent duplicate charges and map each call to a single event.
+     * Auto-generated if not provided. Retrying with the same key returns the original charge.
      * @example "req_abc123"
      */
     idempotencyKey?: string;
@@ -663,8 +686,8 @@ interface ChargeResult {
     success: boolean;
     /** The usage event ID */
     usageEventId: string;
-    /** True if this was an idempotent replay (returned cached result from previous request) */
-    isReplay: boolean;
+    /** True if this was a deduplicated replay (returned cached result from previous request) */
+    isDuplicate: boolean;
     /** Details about the charge */
     charge: {
         /** Unique charge ID */
@@ -682,7 +705,7 @@ interface ChargeResult {
 /**
  * Possible charge statuses.
  */
-type ChargeStatus = 'PENDING' | 'SUBMITTED' | 'CONFIRMED' | 'FAILED' | 'REFUNDED';
+type ChargeStatus = 'PENDING' | 'PENDING_SETTLEMENT' | 'CONFIRMED' | 'FAILED' | 'REFUNDED';
 /**
  * Parameters for tracking usage without billing.
  * Use this for internal visibility, pilots, or pre-billing tracking.
@@ -847,16 +870,22 @@ interface Webhook {
     description: string | null;
     /** Whether the webhook is active */
     isActive: boolean;
+    /** Health status of the webhook endpoint */
+    healthStatus: 'HEALTHY' | 'DEGRADED' | 'UNHEALTHY';
+    /** Number of consecutive delivery failures */
+    consecutiveFailures: number;
+    /** ISO timestamp of last health status change */
+    lastHealthChange: string | null;
     /** ISO timestamp of creation */
     createdAt: string;
     /** ISO timestamp of last update */
     updatedAt: string;
     /** Delivery statistics */
     stats?: {
-        totalDeliveries: number;
-        successfulDeliveries: number;
-        failedDeliveries: number;
-        lastDeliveryAt: string | null;
+        total: number;
+        delivered: number;
+        failed: number;
+        pending: number;
     };
 }
 /**
@@ -944,7 +973,7 @@ interface CreateWorkflowParams {
     /** URL-safe identifier (lowercase alphanumeric with underscores/hyphens) */
     slug: string;
     /** Type of workflow */
-    productSurface?: 'RPC' | 'WEBHOOK' | 'AGENT' | 'PIPELINE' | 'CUSTOM';
+    productSurface?: 'API' | 'RPC' | 'WEBHOOK' | 'AGENT' | 'PIPELINE' | 'CUSTOM';
     /** Optional description */
     description?: string;
     /** Additional metadata */
@@ -958,6 +987,8 @@ interface Workflow {
     name: string;
     slug: string;
     productSurface: string;
+    /** Blockchain chain (if applicable) */
+    chain: string | null;
     description: string | null;
     isActive: boolean;
     createdAt: string;
@@ -1231,47 +1262,93 @@ interface RecordRunResult {
     summary: string;
 }
 /**
- * Full run timeline response.
+ * Full run timeline response from GET /runs/:id/timeline.
  */
 interface RunTimeline {
-    run: {
-        id: string;
-        customerId: string;
-        customerName: string | null;
-        workflowId: string;
-        workflowName: string;
-        status: RunStatus;
-        startedAt: string | null;
-        endedAt: string | null;
-        durationMs: number | null;
-        errorMessage: string | null;
-        errorCode: string | null;
-        correlationId: string | null;
-        metadata: Record<string, unknown> | null;
-    };
-    timeline: Array<{
+    runId: string;
+    workflowId: string | null;
+    workflowName: string | null;
+    customerId: string;
+    status: RunStatus;
+    correlationId: string | null;
+    metadata: Record<string, unknown> | null;
+    errorMessage: string | null;
+    errorCode: string | null;
+    startedAt: string | null;
+    endedAt: string | null;
+    durationMs: number | null;
+    events: Array<{
         id: string;
         eventType: string;
-        quantity: number;
-        units: string | null;
+        actionName: string | null;
+        outcome: 'SUCCESS' | 'FAILED' | 'PENDING' | 'TIMEOUT' | 'RETRYING';
+        explanation: string | null;
         description: string | null;
-        costUnits: number | null;
         timestamp: string;
-        correlationId: string | null;
+        durationMs: number | null;
         parentEventId: string | null;
-        charge: {
-            id: string;
-            amountUsdc: string;
-            status: string;
+        retryOfEventId: string | null;
+        attemptNumber: number;
+        retriedByEventId: string | null;
+        costUsdc: string | null;
+        isRetry: boolean;
+        retryChain: {
+            totalAttempts: number;
+            finalOutcome: string;
+            events: string[];
+        } | null;
+        metadata: {
+            usageType: string;
+            quantity: number;
+            units: string | null;
         } | null;
     }>;
+    anomalies: Array<{
+        id: string;
+        type: string;
+        severity: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+        title: string;
+        explanation: string;
+        relatedEventIds: string[];
+        detectedAt: string;
+        status: 'OPEN' | 'INVESTIGATING' | 'RESOLVED' | 'FALSE_POSITIVE' | 'IGNORED';
+    }>;
+    summary: {
+        totalEvents: number;
+        byType: Record<string, number>;
+        byOutcome: Record<string, number>;
+        retriedEvents: number;
+        failedEvents: number;
+        totalCostUsdc: string | null;
+    };
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+/**
+ * Run details response from GET /runs/:id.
+ */
+interface RunDetails {
+    id: string;
+    customerId: string;
+    customerName: string | null;
+    workflowId: string;
+    workflowName: string;
+    status: RunStatus;
+    startedAt: string | null;
+    endedAt: string | null;
+    durationMs: number | null;
+    errorMessage: string | null;
+    errorCode: string | null;
+    correlationId: string | null;
+    metadata: Record<string, unknown> | null;
     totals: {
         eventCount: number;
         totalQuantity: string;
         totalCostUnits: string;
-        totalChargedUsdc: string;
     };
-    summary: string;
+    _links: {
+        timeline: string;
+    };
 }
 /**
  * Parameters for wrapping an external API call with usage tracking.
@@ -1376,6 +1453,14 @@ declare class Drip {
     private readonly baseUrl;
     private readonly timeout;
     private readonly resilience;
+    /**
+     * The type of API key being used.
+     *
+     * - `'secret'` — Full access (sk_live_... / sk_test_...)
+     * - `'public'` — Client-safe, restricted access (pk_live_... / pk_test_...)
+     * - `'unknown'` — Key format not recognized (legacy or custom)
+     */
+    readonly keyType: 'secret' | 'public' | 'unknown';
     /**
      * Creates a new Drip SDK client.
      *
@@ -1386,23 +1471,29 @@ declare class Drip {
      * ```typescript
      * // Basic usage
      * const drip = new Drip({
-     *   apiKey: 'drip_live_abc123...',
+     *   apiKey: 'sk_live_...',
      * });
      *
      * // With production resilience (recommended)
      * const drip = new Drip({
-     *   apiKey: 'drip_live_abc123...',
+     *   apiKey: 'sk_live_...',
      *   resilience: true,
      * });
      *
      * // High throughput mode
      * const drip = new Drip({
-     *   apiKey: 'drip_live_abc123...',
+     *   apiKey: 'sk_live_...',
      *   resilience: 'high-throughput',
      * });
      * ```
      */
-    constructor(config: DripConfig);
+    constructor(config?: DripConfig);
+    /**
+     * Asserts that the SDK was initialized with a secret key (sk_).
+     * Throws a clear error if a public key is being used for a secret-key-only operation.
+     * @internal
+     */
+    private assertSecretKey;
     /**
      * Makes an authenticated request to the Drip API.
      * @internal
@@ -1720,8 +1811,11 @@ declare class Drip {
      * ```
      */
     getChargeStatus(chargeId: string): Promise<{
+        id: string;
         status: ChargeStatus;
-        txHash?: string;
+        txHash: string | null;
+        confirmedAt: string | null;
+        failureReason: string | null;
     }>;
     /**
      * Creates a checkout session to add funds to a customer's account.
@@ -1874,8 +1968,8 @@ declare class Drip {
      * @example
      * ```typescript
      * const workflow = await drip.createWorkflow({
-     *   name: 'Prescription Intake',
-     *   slug: 'prescription_intake',
+     *   name: 'Document Processing',
+     *   slug: 'doc_processing',
      *   productSurface: 'AGENT',
      * });
      * ```
@@ -1940,33 +2034,53 @@ declare class Drip {
         totalCostUnits: string | null;
     }>;
     /**
-     * Gets a run's full timeline with events and computed totals.
+     * Gets run details with summary totals.
+     *
+     * For full event history with retry chains and anomalies, use `getRunTimeline()`.
+     *
+     * @param runId - The run ID
+     * @returns Run details with totals
+     *
+     * @example
+     * ```typescript
+     * const run = await drip.getRun('run_abc123');
+     * console.log(`Status: ${run.status}, Events: ${run.totals.eventCount}`);
+     * ```
+     */
+    getRun(runId: string): Promise<RunDetails>;
+    /**
+     * Gets a run's full timeline with events, anomalies, and analytics.
      *
      * This is the key endpoint for debugging "what happened" in an execution.
      *
      * @param runId - The run ID
-     * @returns Full timeline with events and summary
+     * @param options - Pagination and filtering options
+     * @returns Full timeline with events, anomalies, and summary
      *
      * @example
      * ```typescript
-     * const { run, timeline, totals, summary } = await drip.getRunTimeline('run_abc123');
+     * const timeline = await drip.getRunTimeline('run_abc123');
      *
-     * console.log(`Status: ${run.status}`);
-     * console.log(`Summary: ${summary}`);
-     * console.log(`Total cost: ${totals.totalCostUnits}`);
+     * console.log(`Status: ${timeline.status}`);
+     * console.log(`Events: ${timeline.summary.totalEvents}`);
      *
-     * for (const event of timeline) {
-     *   console.log(`${event.eventType}: ${event.quantity} ${event.units}`);
+     * for (const event of timeline.events) {
+     *   console.log(`${event.eventType}: ${event.outcome}`);
      * }
      * ```
      */
-    getRunTimeline(runId: string): Promise<RunTimeline>;
+    getRunTimeline(runId: string, options?: {
+        limit?: number;
+        cursor?: string;
+        includeAnomalies?: boolean;
+        collapseRetries?: boolean;
+    }): Promise<RunTimeline>;
     /**
      * Emits an event to a run.
      *
-     * Events can be stored idempotently when an `idempotencyKey` is provided.
+     * Each event is assigned a unique idempotency key (auto-generated if not provided).
+     * This maps each inference or API call to a single trackable event.
      * Use `Drip.generateIdempotencyKey()` for deterministic key generation.
-     * If `idempotencyKey` is omitted, repeated calls may create duplicate events.
      *
      * @param params - Event parameters
      * @returns The created event
@@ -2007,10 +2121,13 @@ declare class Drip {
         success: boolean;
         created: number;
         duplicates: number;
+        skipped: number;
         events: Array<{
             id: string;
             eventType: string;
             isDuplicate: boolean;
+            skipped?: boolean;
+            reason?: string;
         }>;
     }>;
     /**
@@ -2135,7 +2252,7 @@ declare class Drip {
      * // Record a complete agent run in one call
      * const result = await drip.recordRun({
      *   customerId: 'cust_123',
-     *   workflow: 'prescription_intake',  // Auto-creates if doesn't exist
+     *   workflow: 'doc_processing',  // Auto-creates if doesn't exist
      *   events: [
      *     { eventType: 'agent.start', description: 'Started processing' },
      *     { eventType: 'tool.ocr', quantity: 3, units: 'pages', costUnits: 0.15 },
@@ -2154,7 +2271,7 @@ declare class Drip {
      * // Record a failed run with error details
      * const result = await drip.recordRun({
      *   customerId: 'cust_123',
-     *   workflow: 'prescription_intake',
+     *   workflow: 'doc_processing',
      *   events: [
      *     { eventType: 'agent.start', description: 'Started processing' },
      *     { eventType: 'tool.ocr', quantity: 1, units: 'pages' },
@@ -2167,6 +2284,11 @@ declare class Drip {
      * ```
      */
     recordRun(params: RecordRunParams): Promise<RecordRunResult>;
+    /**
+     * 4-step orchestration fallback for servers without POST /runs/record.
+     * @internal
+     */
+    private _recordRunFallback;
     /**
      * Generates a deterministic idempotency key.
      *
@@ -2326,6 +2448,33 @@ declare class Drip {
     createStreamMeter(options: StreamMeterOptions): StreamMeter;
 }
 
+/**
+ * Pre-initialized Drip client singleton.
+ *
+ * Uses lazy initialization - only creates the client when first accessed.
+ * Reads `DRIP_API_KEY` from environment variables.
+ *
+ * @example
+ * ```typescript
+ * import { drip } from '@drip-sdk/node';
+ *
+ * // Track usage with one line
+ * await drip.trackUsage({ customerId: 'cust_123', meter: 'api_calls', quantity: 1 });
+ *
+ * // Charge with one line
+ * await drip.charge({ customerId: 'cust_123', meter: 'api_calls', quantity: 1 });
+ *
+ * // Record a run
+ * await drip.recordRun({
+ *   customerId: 'cust_123',
+ *   workflow: 'agent-run',
+ *   events: [{ eventType: 'llm.call', quantity: 1000, units: 'tokens' }],
+ *   status: 'COMPLETED',
+ * });
+ * ```
+ */
+declare const drip: Drip;
+
 // @ts-ignore
 export = Drip;
-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, isRetryableError };
+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 RunDetails, 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, isRetryableError };