# TypeScript

> Track any AI interaction with begin() / end()

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install voxmithai
  ```

  ```bash pnpm theme={null}
  pnpm add voxmithai
  ```

  ```bash yarn theme={null}
  yarn add voxmithai
  ```
</CodeGroup>

## Integrate

```typescript theme={null}
import * as voxmith from 'voxmithai';

voxmith.init('your-org-id');
```

Get your org ID from [app.voxmith.com](https://app.voxmith.com).

## Track interactions

```typescript theme={null}
const interaction = voxmith.begin({ userId: 'u-123', agentName: 'my-agent', input: '...' });
// ... your AI call ...
interaction.end('...');
```

Latency is auto-calculated. For errors:

```typescript theme={null}
interaction.end('Error: timeout', false);
```

## Group into conversations

```typescript theme={null}
const conversationId = crypto.randomUUID();

const t1 = voxmith.begin({ userId: 'u-123', agentName: 'my-agent', input: 'Hello', conversationId });
t1.end('Hi!');

const t2 = voxmith.begin({ userId: 'u-123', agentName: 'my-agent', input: 'Follow-up', conversationId });
t2.end('Sure!');
```

## Identify users

```typescript theme={null}
voxmith.identify('u-123', { plan: 'pro', role: 'admin' });
```

## Custom properties

```typescript theme={null}
const interaction = voxmith.begin({ userId: 'u-123', agentName: 'my-agent', input: '...' });
interaction.setProperties({ model: 'gpt-4', tokens: '150' });
interaction.end('...');
```

## Retrieve an interaction by ID

Useful when you need to complete an interaction from a different function or callback:

```typescript theme={null}
voxmith.begin({ userId: 'u-123', agentName: 'my-agent', input: '...', interactionId: 'req-1' });

// elsewhere...
const interaction = voxmith.getInteraction('req-1');
interaction?.end('...');
```

## Configuration

```typescript theme={null}
voxmith.init('your-org-id', { endpoint: 'https://api.voxmith.com', debug: true });
```

| Option | Type | Default | Description |
| - | - | - | - |
| `endpoint` | `string` | `https://api.voxmith.com` | API endpoint |
| `debug` | `boolean` | `false` | Enable debug logging |

## Cleanup

```typescript theme={null}
await voxmith.shutdown(); // flushes and cleans up
```

## What appears in Voxmith

* **Conversations** grouped by `conversationId`.
* **User-level analytics** grouped by `userId`.
* **Events** for every tracked interaction.
* Unsuccessful interactions remain visible in **Events** with `success=false`.

## Verify

Run one `begin()` / `end()` interaction, then open [app.voxmith.com](https://app.voxmith.com). Check **Events** first, then **Conversations**.

## Troubleshooting

* Confirm `voxmith.init('your-org-id')` runs before tracking.
* Await `voxmith.shutdown()` before short-lived scripts exit.
* Confirm the endpoint is `https://api.voxmith.com` unless you intentionally use another endpoint.

## Next steps

* [Conversations](/using-conversations): review how TypeScript interactions are grouped.
* [Events](/using-events): inspect the exact records the SDK sent.
* [Intents](/using-intents): organize production conversations by what users wanted.