@drip-sdk/node 1.0.10 → 1.1.1

package/dist/core.d.cts

@@ -0,0 +1,762 @@
+/**
+ * Drip SDK Core - Essential API for pilots and new integrations
+ *
+ * This SDK focuses on two core concepts:
+ * - **Usage tracking**: trackUsage() for recording usage without billing
+ * - **Execution logging**: recordRun() and related methods for tracking runs/events
+ *
+ * For billing, webhooks, cost estimation, and advanced features:
+ * `import { Drip } from '@drip-sdk/node'`
+ *
+ * @packageDocumentation
+ */
+/**
+ * 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.
+     * 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 tracking, customers, runs, and events.
+     *
+     * @example "sk_live_abc123..." or "pk_live_abc123..."
+     */
+    apiKey?: string;
+    /**
+     * Base URL for the Drip API. Defaults to production API.
+     * Falls back to `DRIP_BASE_URL` environment variable if not provided.
+     * @default "https://drip-app-hlunj.ondigitalocean.app/v1"
+     */
+    baseUrl?: string;
+    /**
+     * Request timeout in milliseconds.
+     * @default 30000
+     */
+    timeout?: number;
+}
+/**
+ * Parameters for creating a new customer.
+ */
+interface CreateCustomerParams {
+    /**
+     * Your internal customer/user ID for reconciliation.
+     * @example "user_12345"
+     */
+    externalCustomerId?: string;
+    /**
+     * The customer's Drip Smart Account address (derived from their EOA).
+     * @example "0x1234567890abcdef..."
+     */
+    onchainAddress: string;
+    /**
+     * Additional metadata to store with the customer.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * A Drip customer record.
+ */
+interface Customer {
+    /** Unique customer ID in Drip */
+    id: 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 */
+    onchainAddress: string;
+    /** Custom metadata */
+    metadata: Record<string, unknown> | null;
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+}
+/**
+ * Options for listing customers.
+ */
+interface ListCustomersOptions {
+    /**
+     * Maximum number of customers to return (1-100).
+     * @default 100
+     */
+    limit?: number;
+    /**
+     * Filter by customer status.
+     */
+    status?: 'ACTIVE' | 'LOW_BALANCE' | 'PAUSED';
+}
+/**
+ * Response from listing customers.
+ */
+interface ListCustomersResponse {
+    /** Array of customers */
+    data: Customer[];
+    /** Total count returned */
+    count: number;
+}
+/**
+ * Parameters for tracking usage without billing.
+ */
+interface TrackUsageParams {
+    /**
+     * The Drip customer ID to track usage for.
+     */
+    customerId: string;
+    /**
+     * The meter/usage type (e.g., 'api_calls', 'tokens').
+     */
+    meter: string;
+    /**
+     * The quantity of usage to record.
+     */
+    quantity: number;
+    /**
+     * Unique key to prevent duplicate records.
+     * Auto-generated if not provided, ensuring every call is individually trackable.
+     */
+    idempotencyKey?: string;
+    /**
+     * Human-readable unit label (e.g., 'tokens', 'requests').
+     */
+    units?: string;
+    /**
+     * Human-readable description of this usage event.
+     */
+    description?: string;
+    /**
+     * Additional metadata to attach to this usage event.
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of tracking usage (no billing).
+ */
+interface TrackUsageResult {
+    /** Whether the usage was recorded */
+    success: boolean;
+    /** The usage event ID */
+    usageEventId: string;
+    /** Customer ID */
+    customerId: string;
+    /** Usage type that was recorded */
+    usageType: string;
+    /** Quantity recorded */
+    quantity: number;
+    /** Whether this customer is internal-only */
+    isInternal: boolean;
+    /** Confirmation message */
+    message: string;
+}
+/**
+ * Parameters for starting a new run.
+ */
+interface StartRunParams {
+    /** Customer ID this run belongs to */
+    customerId: string;
+    /** Workflow ID this run executes */
+    workflowId: string;
+    /** Your external run ID for correlation */
+    externalRunId?: string;
+    /** Correlation ID for distributed tracing */
+    correlationId?: string;
+    /** Parent run ID for nested runs */
+    parentRunId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Possible run statuses.
+ */
+type RunStatus = 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMEOUT';
+/**
+ * Result of starting a run.
+ */
+interface RunResult {
+    id: string;
+    customerId: string;
+    workflowId: string;
+    workflowName: string;
+    status: RunStatus;
+    correlationId: string | null;
+    createdAt: string;
+}
+/**
+ * Parameters for ending/updating a run.
+ */
+interface EndRunParams {
+    /** New status for the run */
+    status: 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMEOUT';
+    /** Error message if failed */
+    errorMessage?: string;
+    /** Error code for categorization */
+    errorCode?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of ending a run.
+ */
+interface EndRunResult {
+    id: string;
+    status: RunStatus;
+    endedAt: string | null;
+    durationMs: number | null;
+    eventCount: number;
+    totalCostUnits: string | null;
+}
+/**
+ * Parameters for emitting an event to a run.
+ */
+interface EmitEventParams {
+    /** Run ID to attach this event to */
+    runId: string;
+    /** Event type (e.g., "request.start", "llm.call") */
+    eventType: string;
+    /** Quantity of units consumed */
+    quantity?: number;
+    /** Human-readable unit label */
+    units?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Cost in abstract units */
+    costUnits?: number;
+    /** Currency for cost */
+    costCurrency?: string;
+    /** Correlation ID for tracing */
+    correlationId?: string;
+    /** Parent event ID for trace tree */
+    parentEventId?: string;
+    /** OpenTelemetry-style span ID */
+    spanId?: string;
+    /** Idempotency key */
+    idempotencyKey?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of emitting an event.
+ */
+interface EventResult {
+    id: string;
+    runId: string;
+    eventType: string;
+    quantity: number;
+    costUnits: number | null;
+    isDuplicate: boolean;
+    timestamp: string;
+}
+/**
+ * A single event to record in a run.
+ */
+interface RecordRunEvent {
+    /** Event type (e.g., "request.start", "llm.call", "request.end") */
+    eventType: string;
+    /** Quantity of units consumed */
+    quantity?: number;
+    /** Human-readable unit label */
+    units?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Cost in abstract units */
+    costUnits?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Parameters for recording a complete run in one call.
+ */
+interface RecordRunParams {
+    /** Customer ID this run belongs to */
+    customerId: string;
+    /**
+     * Workflow/request type identifier. Examples:
+     * - "rpc-request" for RPC providers
+     * - "api-request" for API providers
+     * - "agent-run" for AI agents
+     *
+     * Auto-creates if it doesn't exist.
+     */
+    workflow: string;
+    /** Events that occurred during the run */
+    events: RecordRunEvent[];
+    /** Final status of the run */
+    status: 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMEOUT';
+    /** Error message if status is FAILED */
+    errorMessage?: string;
+    /** Error code if status is FAILED */
+    errorCode?: string;
+    /** Your external run ID for correlation */
+    externalRunId?: string;
+    /** Correlation ID for distributed tracing */
+    correlationId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of recording a run.
+ */
+interface RecordRunResult {
+    /** The created run */
+    run: {
+        id: string;
+        workflowId: string;
+        workflowName: string;
+        status: RunStatus;
+        durationMs: number | null;
+    };
+    /** Summary of events created */
+    events: {
+        created: number;
+        duplicates: number;
+    };
+    /** Total cost computed */
+    totalCostUnits: string | null;
+    /** Human-readable summary */
+    summary: string;
+}
+/**
+ * Full run timeline response from GET /runs/:id/timeline.
+ */
+interface RunTimeline {
+    runId: string;
+    workflowId: string | null;
+    customerId: string;
+    status: RunStatus;
+    startedAt: string | null;
+    endedAt: string | null;
+    durationMs: number | null;
+    events: Array<{
+        id: string;
+        eventType: string;
+        actionName: string | null;
+        outcome: 'SUCCESS' | 'FAILED' | 'PENDING' | 'TIMEOUT' | 'RETRYING';
+        explanation: string | null;
+        description: string | null;
+        timestamp: string;
+        durationMs: number | null;
+        parentEventId: string | null;
+        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;
+    };
+    _links: {
+        timeline: string;
+    };
+}
+/**
+ * Error thrown by Drip SDK operations.
+ */
+declare class DripError extends Error {
+    statusCode: number;
+    code?: string | undefined;
+    constructor(message: string, statusCode: number, code?: string | undefined);
+}
+/**
+ * Drip SDK Core - Essential API for pilots and new integrations.
+ *
+ * Two core concepts:
+ * - **Usage tracking**: `trackUsage()` - record usage without billing
+ * - **Execution logging**: `recordRun()` - track request/run lifecycle with events
+ *
+ * For billing (`charge()`), webhooks, and advanced features:
+ * ```typescript
+ * import { Drip } from '@drip-sdk/node';
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { Drip } from '@drip-sdk/node/core';
+ *
+ * const drip = new Drip({ apiKey: process.env.DRIP_API_KEY! });
+ *
+ * // Verify connection
+ * const health = await drip.ping();
+ * console.log(`API healthy: ${health.ok}`);
+ *
+ * // Track usage (no billing)
+ * await drip.trackUsage({
+ *   customerId: 'cust_123',
+ *   meter: 'api_calls',
+ *   quantity: 1,
+ * });
+ *
+ * // Record a complete request/run with events
+ * const result = await drip.recordRun({
+ *   customerId: 'cust_123',
+ *   workflow: 'rpc-request',  // or 'api-request', 'agent-run'
+ *   events: [
+ *     { eventType: 'request.start' },
+ *     { eventType: 'llm.call', quantity: 1500, units: 'tokens' },
+ *     { eventType: 'request.end' },
+ *   ],
+ *   status: 'COMPLETED',
+ * });
+ *
+ * console.log(result.summary);
+ * ```
+ */
+declare class Drip {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    /**
+     * 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.
+     *
+     * @param config - Configuration options (all optional, reads from env vars)
+     * @throws {Error} If apiKey is not provided and DRIP_API_KEY env var is not set
+     *
+     * @example
+     * ```typescript
+     * // Option 1: Explicit config
+     * const drip = new Drip({ apiKey: 'your-api-key' });
+     *
+     * // Option 2: Auto-config from environment (recommended)
+     * // Set DRIP_API_KEY env var, then:
+     * const drip = new Drip();
+     *
+     * // Option 3: Use pre-initialized singleton
+     * import { drip } from '@drip-sdk/node';
+     * ```
+     */
+    constructor(config?: DripConfig);
+    /**
+     * Makes an authenticated request to the Drip API.
+     * @internal
+     */
+    private request;
+    /**
+     * Pings the Drip API to check connectivity and measure latency.
+     *
+     * Use this to verify:
+     * - API key is valid
+     * - Base URL is correct
+     * - Network connectivity works
+     *
+     * @returns Health status with latency information
+     * @throws {DripError} If the request fails or times out
+     *
+     * @example
+     * ```typescript
+     * const health = await drip.ping();
+     * if (health.ok) {
+     *   console.log(`API healthy, latency: ${health.latencyMs}ms`);
+     * } else {
+     *   console.error(`API unhealthy: ${health.status}`);
+     * }
+     * ```
+     */
+    ping(): Promise<{
+        ok: boolean;
+        status: string;
+        latencyMs: number;
+        timestamp: number;
+    }>;
+    /**
+     * Creates a new customer in your Drip account.
+     *
+     * @param params - Customer creation parameters
+     * @returns The created customer
+     * @throws {DripError} If creation fails (e.g., duplicate customer)
+     *
+     * @example
+     * ```typescript
+     * const customer = await drip.createCustomer({
+     *   onchainAddress: '0x1234567890abcdef...',
+     *   externalCustomerId: 'user_123',
+     * });
+     * ```
+     */
+    createCustomer(params: CreateCustomerParams): Promise<Customer>;
+    /**
+     * Retrieves a customer by their Drip ID.
+     *
+     * @param customerId - The Drip customer ID
+     * @returns The customer details
+     * @throws {DripError} If customer not found (404)
+     */
+    getCustomer(customerId: string): Promise<Customer>;
+    /**
+     * Lists all customers for your business.
+     *
+     * @param options - Optional filtering and pagination
+     * @returns List of customers
+     */
+    listCustomers(options?: ListCustomersOptions): Promise<ListCustomersResponse>;
+    /**
+     * Records usage for tracking WITHOUT billing.
+     *
+     * Use this for:
+     * - Pilot programs (track before billing)
+     * - Internal team usage
+     * - Pre-billing tracking before customer setup
+     *
+     * For actual billing, use `charge()` from the full SDK.
+     *
+     * @param params - Usage tracking parameters
+     * @returns The tracked usage event
+     *
+     * @example
+     * ```typescript
+     * const result = await drip.trackUsage({
+     *   customerId: 'cust_abc123',
+     *   meter: 'api_calls',
+     *   quantity: 100,
+     *   description: 'API calls during pilot',
+     * });
+     *
+     * console.log(`Tracked: ${result.usageEventId}`);
+     * ```
+     */
+    trackUsage(params: TrackUsageParams): Promise<TrackUsageResult>;
+    private createWorkflow;
+    private listWorkflows;
+    /**
+     * Starts a new run for tracking execution.
+     *
+     * @param params - Run parameters
+     * @returns The started run
+     *
+     * @example
+     * ```typescript
+     * const run = await drip.startRun({
+     *   customerId: 'cust_abc123',
+     *   workflowId: 'wf_xyz789',
+     * });
+     *
+     * // Emit events during execution...
+     * await drip.emitEvent({ runId: run.id, eventType: 'llm.call', quantity: 1000 });
+     *
+     * // End the run
+     * await drip.endRun(run.id, { status: 'COMPLETED' });
+     * ```
+     */
+    startRun(params: StartRunParams): Promise<RunResult>;
+    /**
+     * Ends a run with a final status.
+     *
+     * @param runId - The run ID to end
+     * @param params - End parameters including status
+     * @returns Updated run info
+     */
+    endRun(runId: string, params: EndRunParams): Promise<EndRunResult>;
+    /**
+     * 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.
+     *
+     * @param runId - The run ID
+     * @param options - Pagination and filtering options
+     * @returns Full timeline with events, anomalies, and summary
+     *
+     * @example
+     * ```typescript
+     * const timeline = await drip.getRunTimeline('run_abc123');
+     *
+     * console.log(`Status: ${timeline.status}`);
+     * console.log(`Events: ${timeline.summary.totalEvents}`);
+     *
+     * for (const event of timeline.events) {
+     *   console.log(`${event.eventType}: ${event.outcome}`);
+     * }
+     * ```
+     */
+    getRunTimeline(runId: string, options?: {
+        limit?: number;
+        cursor?: string;
+        includeAnomalies?: boolean;
+        collapseRetries?: boolean;
+    }): Promise<RunTimeline>;
+    /**
+     * Emits an event to a run.
+     *
+     * @param params - Event parameters
+     * @returns The created event
+     *
+     * @example
+     * ```typescript
+     * await drip.emitEvent({
+     *   runId: run.id,
+     *   eventType: 'llm.call',
+     *   quantity: 1500,
+     *   units: 'tokens',
+     *   description: 'GPT-4 completion',
+     * });
+     * ```
+     */
+    emitEvent(params: EmitEventParams): Promise<EventResult>;
+    /**
+     * Emits multiple events in a single request.
+     *
+     * @param events - Array of events to emit
+     * @returns Summary of created events
+     */
+    emitEventsBatch(events: Array<EmitEventParams>): Promise<{
+        success: boolean;
+        created: number;
+        duplicates: number;
+        skipped: number;
+        events: Array<{
+            id: string;
+            eventType: string;
+            isDuplicate: boolean;
+            skipped?: boolean;
+            reason?: string;
+        }>;
+    }>;
+    /**
+     * Records a complete request/run in a single call.
+     *
+     * This is the **hero method** for tracking execution. It combines:
+     * - Workflow creation (auto-creates if needed)
+     * - Run creation
+     * - Event emission
+     * - Run completion
+     *
+     * @param params - Run parameters including events
+     * @returns The created run with event summary
+     *
+     * @example
+     * ```typescript
+     * // RPC provider example
+     * const result = await drip.recordRun({
+     *   customerId: 'cust_123',
+     *   workflow: 'rpc-request',
+     *   events: [
+     *     { eventType: 'request.start' },
+     *     { eventType: 'eth_call', quantity: 1 },
+     *     { eventType: 'request.end' },
+     *   ],
+     *   status: 'COMPLETED',
+     * });
+     *
+     * // API provider example
+     * const result = await drip.recordRun({
+     *   customerId: 'cust_123',
+     *   workflow: 'api-request',
+     *   events: [
+     *     { eventType: 'request.start' },
+     *     { eventType: 'llm.call', quantity: 2000, units: 'tokens' },
+     *     { eventType: 'request.end' },
+     *   ],
+     *   status: 'COMPLETED',
+     * });
+     *
+     * console.log(result.summary);
+     * // Output: "✓ Rpc Request: 3 events recorded (152ms)"
+     * ```
+     */
+    recordRun(params: RecordRunParams): Promise<RecordRunResult>;
+}
+
+/**
+ * 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 });
+ *
+ * // 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 CreateCustomerParams, type Customer, Drip, type DripConfig, DripError, type EmitEventParams, type EndRunParams, type EndRunResult, type EventResult, type ListCustomersOptions, type ListCustomersResponse, type RecordRunEvent, type RecordRunParams, type RecordRunResult, type RunDetails, type RunResult, type RunStatus, type RunTimeline, type StartRunParams, type TrackUsageParams, type TrackUsageResult, drip };