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

# JavaScript SDK

> TypeScript-first client for Node.js and browsers.

## Installation

```bash theme={null}
npm install colacloud
```

## Quick Start

```typescript theme={null}
import { ColaCloud } from 'colacloud';

const client = new ColaCloud({ apiKey: 'cola_xxxx' });

// Search COLAs
const results = await client.colas.list({
  q: "Tito's",
  productType: 'distilled spirits',
  abvMin: 35,
  perPage: 10,
});

for (const cola of results.data) {
  console.log(`${cola.brand_name} - ${cola.product_name}`);
}

// Get a specific COLA with images and barcodes
const cola = await client.colas.get('24001001000001');
for (const image of cola.images) {
  console.log(image.image_url);
}

// Barcode lookup
const matches = await client.barcodes.lookup('012345678901');
console.log(`Found ${matches.total_colas} COLAs`);
```

<Note>
  Request parameters use **camelCase** (e.g., `brandName`, `productType`), but response fields use **snake\_case** (e.g., `brand_name`, `product_type`) to match the API.
</Note>

## Filtering

The COLA list endpoint supports generic text search plus structured filters for TTB product type, derived category/subcategory, ABV, package size, container type, permit number, and barcode.

```typescript theme={null}
const results = await client.colas.list({
  q: 'molson coors',
  category: 'Beer',
  derivedSubcategory: 'Beer > Ale',
  containerType: 'can',
  volumeUnit: 'fluid ounces',
  volumeMin: 12,
  volumeMax: 16,
});
```

Use `q` when you are not sure whether a word belongs to a brand, product, permit, or applicant/company name.

## Auto-Pagination

Iterate through all matching results without managing pages:

```typescript theme={null}
for await (const cola of client.colas.iterate({ q: 'bourbon' })) {
  console.log(`${cola.ttb_id}: ${cola.brand_name}`);
}

for await (const permittee of client.permittees.iterate({ state: 'CA' })) {
  console.log(`${permittee.company_name}: ${permittee.colas} COLAs`);
}
```

## Permittees

```typescript theme={null}
// Search permittees
const permittees = await client.permittees.list({ state: 'NY', isActive: true });
for (const p of permittees.data) {
  console.log(`${p.company_name} (${p.permit_number})`);
}

// Get a single permittee with recent COLAs
const permittee = await client.permittees.get('NY-I-12345');
console.log(`Recent COLAs: ${permittee.recent_colas.length}`);
```

## Usage Stats

```typescript theme={null}
const usage = await client.usage.get();
console.log(`Detail views: ${usage.detail_views.used} / ${usage.detail_views.limit}`);
console.log(`List records: ${usage.list_records.used} / ${usage.list_records.limit}`);
```

## Browser Usage

The SDK works in browsers with bundlers like Vite, Webpack, or esbuild:

```typescript theme={null}
import { ColaCloud } from 'colacloud';

const client = new ColaCloud({ apiKey: 'cola_xxxx' });
```

## Authentication

Pass your API key directly to the client:

```typescript theme={null}
const client = new ColaCloud({ apiKey: 'cola_xxxx' });
```

## Links

* [GitHub](https://github.com/cola-cloud-us/colacloud-js)
* [npm](https://www.npmjs.com/package/colacloud)