> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowsbuilt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Type Reference

> Complete TypeScript type definitions for the ChurnKit SDK.

## Core types

### ChurnKitOptions

```typescript theme={null}
interface ChurnKitOptions {
  apiKey: string
  env?: 'production' | 'staging'
  baseUrl?: string
  timeout?: number                                   // default: 15000ms
  maxRetries?: number                                // default: 3
  onRequest?: (ctx: RequestContext) => void | Promise<void>
  onResponse?: (ctx: ResponseContext) => void | Promise<void>
}
```

### CallOptions

```typescript theme={null}
interface CallOptions {
  signal?: AbortSignal
}
```

### UserTraits

```typescript theme={null}
interface UserTraits {
  plan?: string
  mrr?: number
  email?: string
  name?: string
  company?: string
  signedUpAt?: string
  [key: string]: string | number | boolean | null | undefined
}
```

### EventProperties

```typescript theme={null}
interface EventProperties {
  [key: string]: string | number | boolean | null | undefined
}
```

### BulkEventItem

```typescript theme={null}
interface BulkEventItem {
  userId: string
  event: string
  properties?: EventProperties
  timestamp?: string   // ISO 8601
}
```

***

## Risk types

### RiskScore

```typescript theme={null}
interface RiskScore {
  userId: string
  score: number         // 0.0 → 1.0
  tier: RiskTier        // 'low' | 'medium' | 'high'
  signals: string[]
  recommendation: string
}
```

### AtRiskUser

```typescript theme={null}
interface AtRiskUser {
  userId: string
  score: number
  tier: RiskTier
  signals: string[]
  recommendation: string
}
```

### AtRiskResult

```typescript theme={null}
interface AtRiskResult {
  users: AtRiskUser[]
  total: number
  offset: number
  limit: number
}
```

### AtRiskOptions

```typescript theme={null}
interface AtRiskOptions {
  threshold?: number    // default: 0.5
  plan?: string
  limit?: number        // default: 50, max: 200
  offset?: number       // default: 0
  signal?: AbortSignal
}
```

### AtRiskAllOptions

```typescript theme={null}
interface AtRiskAllOptions {
  threshold?: number
  plan?: string
  pageSize?: number     // default: 100
}
```

### RiskTier

```typescript theme={null}
type RiskTier = 'low' | 'medium' | 'high'
```

***

## Watch types

### WatchOptions

```typescript theme={null}
interface WatchOptions {
  threshold: number          // required, 0–1
  webhook: string            // required, https:// URL
  cooldown: CooldownString   // required, e.g. '24h', '7d'
}
```

### CooldownString

A string matching `^[1-9]\d*[dh]$`:

```typescript theme={null}
type CooldownString = string  // '1h', '24h', '7d', '30d', etc.
```

### WatchedUser

```typescript theme={null}
interface WatchedUser {
  userId: string
  threshold: number
  webhook: string
  cooldown: string
}
```

***

## Batcher types

### BatcherOptions

```typescript theme={null}
interface BatcherOptions {
  flushInterval?: number              // ms, default: 5000
  maxSize?: number                    // default: 100, max: 500
  onFlush?: (count: number) => void
  onError?: (err: unknown) => void
}
```

### EventBatcher

```typescript theme={null}
interface EventBatcher {
  push(event: BulkEventItem): void
  flush(): Promise<number>
  destroy(): Promise<void>
}
```

***

## Observability types

### RequestContext

```typescript theme={null}
interface RequestContext {
  method: string
  url: string
  headers: Record<string, string>  // mutable — add custom headers here
  body?: unknown
}
```

### ResponseContext

```typescript theme={null}
interface ResponseContext {
  method: string
  url: string
  status: number
  durationMs: number
  attempt: number   // 0 = first attempt, 1 = first retry, etc.
}
```

***

## Error types

### ChurnKitError

```typescript theme={null}
class ChurnKitError extends Error {
  readonly status?: number
  readonly code?: ErrorCode | string
}
```

### ErrorCode

```typescript theme={null}
const ErrorCode = {
  ABORTED:            'ABORTED',
  TIMEOUT:            'TIMEOUT',
  NETWORK_ERROR:      'NETWORK_ERROR',
  VALIDATION_ERROR:   'VALIDATION_ERROR',
  UNAUTHORIZED:       'UNAUTHORIZED',
  FORBIDDEN:          'FORBIDDEN',
  NOT_FOUND:          'NOT_FOUND',
  RATE_LIMITED:       'RATE_LIMITED',
  SERVER_ERROR:       'SERVER_ERROR',
  PAYLOAD_TOO_LARGE:  'PAYLOAD_TOO_LARGE',
} as const
```