@drip-sdk/node 1.1.0 → 1.1.1

package/dist/index.d.cts

@@ -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;
     /**
@@ -645,8 +657,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;
@@ -944,7 +956,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 */
@@ -1231,47 +1243,88 @@ 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;
+    customerId: string;
+    status: RunStatus;
+    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 +1429,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 +1447,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
@@ -1874,8 +1941,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 +2007,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 +2094,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 +2225,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 +2244,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' },
@@ -2326,6 +2416,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 };