Skip to main content

​
Installation

npm install colacloud

​
Quick Start

import { ColaCloud } from 'colacloud';

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

// Search COLAs
const results = await client.colas.list({
  brandName: "Tito's",
  productType: 'distilled spirits',
  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`);
Request parameters use camelCase (e.g., brandName, productType), but response fields use snake_case (e.g., brand_name, product_type) to match the API.

​
Auto-Pagination

Iterate through all matching results without managing pages: 
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

// 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

const usage = await client.usage.get();
console.log(`${usage.requests_used} / ${usage.monthly_limit} requests used`);

​
Rate Limit Info

Every method has a WithRateLimit variant that returns rate limit headers alongside data: 
const { data, rateLimit } = await client.colas.listWithRateLimit({ q: 'wine' });
console.log(`Remaining: ${rateLimit?.remaining}`);

// Also available for other resources
const { data: cola, rateLimit: rl } = await client.colas.getWithRateLimit('24001001000001');
const { data: usage, rateLimit: rl2 } = await client.usage.getWithRateLimit();

​
Browser Usage

The SDK works in browsers with bundlers like Vite, Webpack, or esbuild: 
import { ColaCloud } from 'colacloud';

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

​
Authentication

Pass your API key directly to the client: 
const client = new ColaCloud({ apiKey: 'cola_xxxx' });