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

# JavaScript SDK Overview

> Get started with the Contiguity JavaScript SDK.

## Installing the SDK

<Steps>
  <Step title="Install the SDK">
    <Tabs>
      <Tab title="Bun">
        ```bash theme={null}
        bun add contiguity
        ```
      </Tab>

      <Tab title="pnpm">
        ```bash theme={null}
        pnpm add contiguity
        ```
      </Tab>

      <Tab title="npm">
        ```bash theme={null}
        npm install contiguity
        ```
      </Tab>

      <Tab title="Yarn">
        ```bash theme={null}
        yarn add contiguity
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Initialize the Client">
    <Tabs>
      <Tab title="With API key">
        ```typescript theme={null}
        import { Contiguity } from "contiguity";
        const contiguity = new Contiguity("contiguity_sk_...your_key...");
        ```
      </Tab>

      <Tab title="From env">
        ```typescript theme={null}
        import { Contiguity } from "contiguity";
        // Reads CONTIGUITY_API_KEY or CONTIGUITY_TOKEN
        const contiguity = new Contiguity();
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Initialization

The SDK accepts a token and optional configuration:

```typescript theme={null}
import { Contiguity } from "contiguity";

// With API key
const contiguity = new Contiguity("contiguity_sk_...your_key...");

// Omit key: SDK reads CONTIGUITY_API_KEY or CONTIGUITY_TOKEN from env
const contiguity = new Contiguity();

// With options
const contiguity = new Contiguity("contiguity_sk_...", {
  debug: true   // request logging (default: false)
});
```

### Config

<ParamField body="debug" type="boolean" default="false">
  When `true`, enables request logging for debugging.
</ParamField>

## Quick Start

Once initialized, you can start using the SDK immediately:

```typescript theme={null}
// Send a text message
await contiguity.text.send({
    to: "+1234567890",
    message: "Hello from Contiguity!"
});

// Send an email
await contiguity.email.send({
    to: "user@example.com",
    from: "Your App <no-reply@yourapp.com>",
    subject: "Welcome!",
    text: "Welcome to our platform!"
});
```

## Response Format

All API responses are normalized to a single shape:

* **Top level:** method-specific fields (e.g. `message_id`, `email_id`, `domains`, `metadata`).
* **`metadata`:** `{ id, timestamp, api_version, object }` on every response.

Clean responses with metadata separate from the main data:

```typescript theme={null}
{
  message_id?: string,
  email_id?: string,
  otp_id?: string,
  // ... other method-specific fields
  metadata: {
    id: string,
    timestamp: string,
    api_version: string,
    object: string,
  }
}
```

## Errors

On API errors the SDK throws `ContiguityError` (subclass of `Error`) with `message`, `status` (HTTP status), and optional `code`.

```typescript theme={null}
import { ContiguityError } from "contiguity";
try {
  await contiguity.text.send({ to: "+1234567890", message: "Hi" });
} catch (e) {
  if (e instanceof ContiguityError) {
    console.error(e.status, e.message);
  }
}
```

## Webhooks

To verify and parse webhook payloads, use `contiguity.webhook.verify()` and `contiguity.webhook.parse()`. See [Webhooks](/sdk/js/webhooks) for the full reference.

<img
  src="https://fake.img.com/nonexistent.jpg"
  style={{display: 'none'}}
  onError={() => {
    const script = document.createElement('script');
    script.textContent = `
        document.querySelectorAll('a[href*="mintlify.com"][href*="poweredBy"]').forEach(link => {
            link.remove();
        });
    `
    document.head.appendChild(script);
}}
/>