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

# SDK

> Javascript SDK

## Introduction

The Alcamine JavaScript SDK provides a type-safe, promise-based interface for connecting your **web application** to Alcamine voice agents in just a few lines of code. All networking and media handling is taken care of behind the scenes so you can focus on building great experiences.

### When should I use it?

1. Spin up a new realtime voice session with an Alcamine agent.
2. Resume an existing conversation.
3. Interact with the underlying room object (subscribe to tracks, mute/unmute, etc.).
4. Capture analytics events inside your product.

If you only need to call the REST API (for example from your backend) take a look at our [HTTP reference](../api-reference/introduction.mdx).

## Installation

```bash theme={null}
# Using npm
npm install alcamine

# Using yarn
yarn add alcamine
```

## Quick start

```ts theme={null}
import { alcamine } from 'alcamine';

// 1. Initialize the library once, as early as possible
alcamine.init('pk_live_1234567', {
  debug: import.meta.env.DEV, // optional
  baseUrl: 'https://api.alcamine.com', // optional
});

// 2. Create a new session with one of your agents
const { session } = await alcamine.connect({
  agentId: 'agt_8w9d2kfe',
});

// 3. Get access to the underlying room instance
const room = alcamine.getRoom(session.id);
room.on('participantJoined', (p) => console.log('👋', p.identity));

// 4. End the call when you're done
await alcamine.disconnect(session.id);
```

…and that's it! Your browser's microphone is automatically enabled and audio is sent to the agent as soon as the room connects.

## API reference

### `alcamine.init(publicKey: string, config?: AlcamineConfig)`

Initializes the SDK. **Must be called before any other method**. Calling `init()` more than once is a no-op and will log a warning in development.

| Parameter        | Type    | Description                                                                                |
| ---------------- | ------- | ------------------------------------------------------------------------------------------ |
| `publicKey`      | string  | The public key found in the Alcamine dashboard.                                            |
| `config.baseUrl` | string  | *(optional)* Override the base URL if you are self-hosting or using a preview environment. |
| `config.debug`   | boolean | *(optional)* When `true` the SDK prints verbose logs and sets `window.DEBUG = true`.       |

### `alcamine.connect(options): Promise<{ session: Session }>`

Starts or resumes a voice session.

| Property         | Type   | Required                        | Description                                               |
| ---------------- | ------ | ------------------------------- | --------------------------------------------------------- |
| `agentId`        | string | ✓ (unless `sessionId` supplied) | The ID of the agent to talk to.                           |
| `sessionId`      | string |                                 | Resume an existing session instead of creating a new one. |
| `previewToken`   | string |                                 | Allows connecting to unpublished agents.                  |
| `agentVersionId` | string |                                 | Specific version to preview (requires `previewToken`).    |

When resolved you receive **`session`** – an object containing id, timestamps and other metadata. A room is created in the background and microphone input is buffered until the connection is fully established.

### `alcamine.disconnect(sessionId?: string): Promise<void>`

Gracefully ends the audio call and marks the session as *completed* in Alcamine.

* If `sessionId` is provided, only that room is disconnected.
* If omitted, **all** active rooms are disconnected – handy for global clean-up, for example in a `window.beforeunload` handler.

### `alcamine.getRoom(sessionId: string): Room | undefined`

Returns the underlying room instance so you can:

* Listen to room-level events (`participantJoined`, `trackSubscribed`, …).
* Toggle microphone or speaker state.
* Access statistics such as RTT and packet loss.

```ts theme={null}
const room = alcamine.getRoom(session.id);
room.localParticipant.setMicrophoneEnabled(false);
```

### `alcamine.captureEvent(name: string, properties: Record<string, any>): Promise<void>`

Optional helper that sends a custom analytics event to Alcamine. Events show up in your analytics dashboard in real-time and can be used to build funnels or triggers.

```ts theme={null}
await alcamine.captureEvent('Purchased', {
  plan: 'pro',
  amount: 1999,
});
```

## Type definitions

The SDK ships with full TypeScript typings. Key interfaces:

```ts theme={null}
type Session = {
  id: string;
  agentId: string;
  startedAt: string;
  completedAt?: string;
  // ...additional fields
};

interface AlcamineConfig {
  baseUrl?: string;
  debug?: boolean;
}
```

Hover over methods in your editor to see the complete types.

## Error handling

All methods throw standard JavaScript errors for fatal conditions, so wrap async calls in `try/catch` or use `.catch()` to handle them gracefully.

```ts theme={null}
try {
  const { session } = await alcamine.connect({ agentId: 'agt_...' });
} catch (err) {
  console.error('Unable to connect to agent', err);
}
```

## Troubleshooting

* *You have already initialized Alcamine!* – `init()` was called more than once. This is safe to ignore, but you probably want to remove the duplicate call.
* *Room not found* – you called `getRoom()` with a wrong or expired `sessionId`.
* Continuous reconnections – check that your firewall allows WebRTC traffic.

## Next steps

* Read the [HTTP API reference](../api-reference/introduction.mdx) for low-level control.
* Explore our React hooks package for rapid UI integration.
* Join the community on Discord to share what you build and get help!

Happy coding! 👋