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

# TypeScript SDK

> Install and use the Journeybee TypeScript SDK

# TypeScript SDK

The official TypeScript SDK provides typed functions for every API endpoint with full autocomplete and compile-time type checking.

## Installation

Published on npm — [**`@journeybee/sdk`**](https://www.npmjs.com/package/@journeybee/sdk):

```bash theme={null}
npm install @journeybee/sdk
```

## Quick start

```typescript theme={null}
import { client, listPartners, createLead } from "@journeybee/sdk";

// Configure once — all subsequent calls use this config
client.setConfig({
  baseUrl: "https://api.journeybee.io/v1",
  auth: "YOUR_API_KEY",
});

// List partners with search
const { data: partners } = await listPartners({
  query: { search: "acme", per_page: 10 },
});

// Create a lead
const { data: lead } = await createLead({
  body: {
    first_name: "Jane",
    last_name: "Smith",
    email: "jane@example.com",
    partnership_uuid: "partner-uuid-here",
  },
});
```

## Authentication

Pass your API key to `client.setConfig()`. The SDK sends it as a `Bearer` token on every request automatically.

```typescript theme={null}
import { client } from "@journeybee/sdk";

client.setConfig({
  baseUrl: "https://api.journeybee.io/v1",
  auth: "jb_live_your_api_key",
});
```

## Request patterns

Every SDK function accepts an options object with typed `path`, `query`, and `body` fields depending on the endpoint.

### List with pagination and filters

```typescript theme={null}
import { listLeads } from "@journeybee/sdk";

const { data } = await listLeads({
  query: {
    page: 1,
    per_page: 50,
    status: "new",
    search: "acme",
  },
});

// data.data — array of leads
// data.pagination — { page, per_page, total, total_pages }
```

### Get by UUID

```typescript theme={null}
import { getPartner } from "@journeybee/sdk";

const { data: partner } = await getPartner({
  path: { uuid: "partner-uuid" },
});
```

### Create

```typescript theme={null}
import { createDeal } from "@journeybee/sdk";

const { data: deal } = await createDeal({
  body: {
    lead_uuid: "lead-uuid",
    value: 50000,
    currency_uuid: "currency-uuid",
  },
});
```

### Update

```typescript theme={null}
import { updateLead } from "@journeybee/sdk";

const { data: lead } = await updateLead({
  path: { uuid: "lead-uuid" },
  body: { status: "converted" },
});
```

### Delete

```typescript theme={null}
import { deleteLead } from "@journeybee/sdk";

await deleteLead({
  path: { uuid: "lead-uuid" },
});
```

### Sub-resources

```typescript theme={null}
import { addLeadTag, removeLeadTag, listLeadNotes } from "@journeybee/sdk";

// Add a tag
await addLeadTag({
  path: { uuid: "lead-uuid" },
  body: { tag_uuid: "tag-uuid" },
});

// Remove a tag
await removeLeadTag({
  path: { uuid: "lead-uuid", subUuid: "tag-uuid" },
});

// List notes
const { data: notes } = await listLeadNotes({
  path: { uuid: "lead-uuid" },
});
```

## Error handling

SDK functions return `{ data, error, response }`. Check `error` for failures:

```typescript theme={null}
import { getLead } from "@journeybee/sdk";

const { data, error } = await getLead({
  path: { uuid: "nonexistent" },
});

if (error) {
  console.error("API error:", error);
  // error.code — "not_found", "unauthorized", etc.
  // error.message — human-readable description
} else {
  console.log("Lead:", data);
}
```

## Available functions

The SDK exports one function per API endpoint. Function names match the `operationId` in the [API Reference](../apis/openapi.json):

| Domain             | Functions                                                                                            |
| ------------------ | ---------------------------------------------------------------------------------------------------- |
| **Partners**       | `listPartners`, `getPartner`, `createPartner`, `updatePartner`                                       |
| **Leads**          | `listLeads`, `getLead`, `createLead`, `updateLead`, `deleteLead`                                     |
| **Deals**          | `listDeals`, `getDeal`, `createDeal`, `updateDeal`, `deleteDeal`                                     |
| **Tasks**          | `listTasks`, `getTask`, `createTask`, `updateTask`, `deleteTask`                                     |
| **Products**       | `listProducts`, `getProduct`, `createProduct`, `updateProduct`, `deleteProduct`                      |
| **Contacts**       | `listContacts`, `getContact`                                                                         |
| **Commissions**    | `listCommissions`, `getCommission`, `createCommission`, `updateCommission`, `deleteCommission`       |
| **Resources**      | `listResources`, `getResource`, `createResource`, `updateResource`, `deleteResource`                 |
| **Certifications** | `listCertifications`, `getCertification`, `createCertification`, `enrollInCertification`             |
| **Rooms**          | `listRooms`, `getRoom`, `createRoom`, `updateRoom`, `deleteRoom`                                     |
| **Folders**        | `listFolders`, `getFolder`, `createFolder`, `updateFolder`, `deleteFolder`                           |
| **Configuration**  | `listPartnerStages`, `listDealStages`, `listTiers`, `listCategories`, `listTags`, `listCustomFields` |

Plus sub-resource functions like `addLeadTag`, `listLeadNotes`, `createPartnerContact`, `getDealCommission`, `addResourceBlock`, `addRoomBlock`, `addRoomTier`, and more. See the [API Reference](../apis/openapi.json) for the complete list.