> ## 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.

# Configuration

> All ChurnKitOptions — timeouts, retries, environments, and observability hooks.

## ChurnKitOptions

```typescript theme={null}
const churn = new ChurnKit({
  apiKey: string           // required
  env?: 'production' | 'staging'
  baseUrl?: string
  timeout?: number
  maxRetries?: number
  onRequest?: (ctx: RequestContext) => void | Promise<void>
  onResponse?: (ctx: ResponseContext) => void | Promise<void>
})
```

## Options reference

### `apiKey` <span className="text-red-500">required</span>

Your FlowsBuilt API key. Get one from the [Console](https://console.flowsbuilt.com/dashboard/keys).

```typescript theme={null}
new ChurnKit({ apiKey: 'ck_live_abc123' })
```

***

### `env`

Target API environment. Defaults to `'production'`.

| Value          | API endpoint                                         |
| -------------- | ---------------------------------------------------- |
| `'production'` | `https://churnkit-api.vguruprasad91.workers.dev`     |
| `'staging'`    | `https://churnkit-api-dev.vguruprasad91.workers.dev` |

```typescript theme={null}
// Use staging in development
new ChurnKit({ apiKey: 'ck_test_...', env: 'staging' })
```

***

### `baseUrl`

Override the API base URL entirely — takes precedence over `env`. Useful for self-hosted or proxy setups.

```typescript theme={null}
new ChurnKit({ apiKey: '...', baseUrl: 'https://my-proxy.internal/churnkit' })
```

***

### `timeout`

Request timeout in milliseconds. Default: `15000` (15 seconds).

```typescript theme={null}
new ChurnKit({ apiKey: '...', timeout: 5000 }) // fail fast after 5s
```

***

### `maxRetries`

Maximum number of attempts for retryable failures (network errors, 429, 5xx). Default: `3`.

* `1` = no retries (fail fast — use for non-idempotent writes if needed)
* `5` = extra durability for high-stakes calls

```typescript theme={null}
new ChurnKit({ apiKey: '...', maxRetries: 1 }) // disable retries
```

Retries use exponential backoff with jitter.

***

### `onRequest`

Called once before the first HTTP attempt. Use it to inject trace IDs, correlation IDs, or log outgoing requests.

<Note>
  `onRequest` fires **once per SDK call** — not on each retry. Mutations to `ctx.headers` apply to all retry attempts.
</Note>

```typescript theme={null}
import { trace } from '@opentelemetry/api'

new ChurnKit({
  apiKey: '...',
  onRequest: (ctx) => {
    ctx.headers['X-Request-Id'] = crypto.randomUUID()
    ctx.headers['X-Trace-Id'] = trace.getActiveSpan()?.spanContext().traceId ?? ''
  },
})
```

***

### `onResponse`

Called after **every** HTTP response, including each retry attempt. Use it to record per-attempt latency metrics.

```typescript theme={null}
new ChurnKit({
  apiKey: '...',
  onResponse: (ctx) => {
    metrics.histogram('churnkit.latency', ctx.durationMs, {
      status: ctx.status,
      method: ctx.method,
      attempt: ctx.attempt,   // 0 = first, 1 = first retry, etc.
    })
    if (ctx.attempt > 0) {
      logger.warn('ChurnKit retry', { attempt: ctx.attempt, url: ctx.url })
    }
  },
})
```

## Full example

```typescript theme={null}
import ChurnKit from '@vgpprasad91/churnkit-sdk'
import { trace } from '@opentelemetry/api'

export const churn = new ChurnKit({
  apiKey: process.env.CHURNKIT_API_KEY!,
  timeout: 10_000,
  maxRetries: 3,
  onRequest: (ctx) => {
    ctx.headers['X-Request-Id'] = crypto.randomUUID()
    ctx.headers['X-Trace-Id'] = trace.getActiveSpan()?.spanContext().traceId ?? ''
  },
  onResponse: (ctx) => {
    console.log(`[ChurnKit] ${ctx.method} ${ctx.url} → ${ctx.status} in ${ctx.durationMs}ms (attempt ${ctx.attempt})`)
  },
})
```