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

# TypeScript

> Get started with the Greenflash's [TypeScript SDK](https://github.com/greenflash-ai/typescript).

## Basic Usage

Install the package and start logging messages in minutes:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
npm install greenflash
# or
yarn add greenflash
# or
pnpm add greenflash
```

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
import Greenflash from 'greenflash';

const client = new Greenflash({
  apiKey: process.env['GREENFLASH_API_KEY'],
});

// Log your first conversation
client.messages.create({
  productId: 'YOUR_PRODUCT_ID',
  externalUserId: 'USER_ID',
  externalConversationId: 'CONVO_ID',
  messages: [
    { role: 'user', content: 'Hello, how can you help me today?' },
    { role: 'assistant', content: 'I can answer any questions you have!' },
  ],
});
```

### Type Safety

The SDK provides full TypeScript support with built-in types for all requests and responses:

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
import Greenflash from 'greenflash';

const client = new Greenflash({ apiKey: process.env['GREENFLASH_API_KEY'] });

// Type-safe message creation
const params: Greenflash.MessageCreateParams = {
  productId: 'YOUR_PRODUCT_ID',
  externalUserId: 'USER_ID',
  externalConversationId: 'CONVO_ID',
  messages: [{ role: 'user', content: '...' }],
};

const response: Greenflash.CreateResponse = await client.messages.create(params);
```

### Handling Errors Gracefully

The SDK throws specific error classes for different failure scenarios, making error handling straightforward:

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
try {
  await client.messages.create({ /* ... */ });
} catch (err) {
  if (err instanceof Greenflash.APIError) {
    // Handle API-specific errors
    console.log(`API Error ${err.status}: ${err.name}`);
    console.log('Response headers:', err.headers);
  } else {
    // Re-throw unexpected errors
    throw err;
  }
}
```

**Available Error Classes:**

* `AuthenticationError` - Invalid or missing API key
* `PermissionDeniedError` - Insufficient permissions
* `NotFoundError` - Resource not found
* `RateLimitError` - Too many requests
* `ValidationError` - Invalid request data

### Configure Retry Behavior

Automatically retry failed requests with intelligent backoff:

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
// Disable retries globally
const client = new Greenflash({ maxRetries: 0 });

// Override retries per request
client.messages.create({ /* ... */ }, { maxRetries: 5 });
```

**Default Retry Strategy:**

* Retries on connection errors, `408`, `409`, `429`, and `5xx` responses
* Maximum of 2 retries with exponential backoff
* Configurable per client or per request

### Set Request Timeouts

Control how long to wait for responses:

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
// Set global timeout to 20 seconds
const client = new Greenflash({ timeout: 20_000 });

// Override timeout for specific request
client.messages.create({ /* ... */ }, { timeout: 5_000 });
```

**Timeout Behavior:**

* Default timeout: 60 seconds
* Throws `APIConnectionTimeoutError` on timeout
* Configurable globally or per request

## Advanced Features

### Access Raw HTTP Response

Get full control over the HTTP response for custom handling:

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
// Get raw response object
const raw = await client.messages.create({ /* ... */ }).asResponse();
console.log('Custom header:', raw.headers.get('X-My-Header'));

// Get both data and response
const { data, response } = await client.messages.create({ /* ... */ }).withResponse();
console.log('Response status:', response.status);
console.log('Response data:', data);
```

### Configure Logging

Control SDK logging verbosity and use custom loggers:

```typescript theme={"theme":{"light":"github-light","dark":"vesper"}}
// Set log level via environment variable
// GREENFLASH_LOG=debug

// Or configure programmatically
const client = new Greenflash({
  logLevel: 'debug',
  logger: pino() // Use custom logger like pino
});
```

**Log Levels:**

* `error` - Only errors (default)
* `warn` - Warnings and errors
* `info` - General information
* `debug` - Detailed debugging info