colacloud 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,580 @@
+/**
+ * COLA Cloud API TypeScript Types
+ */
+/**
+ * Configuration options for the ColaCloud client
+ */
+interface ColaCloudConfig {
+    /** Your COLA Cloud API key */
+    apiKey: string;
+    /** Base URL for the API (defaults to https://app.colacloud.us/api/v1) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (defaults to 30000) */
+    timeout?: number;
+}
+/**
+ * Pagination metadata returned with list endpoints
+ */
+interface Pagination {
+    /** Current page number (1-indexed) */
+    page: number;
+    /** Number of items per page */
+    per_page: number;
+    /** Total number of items across all pages */
+    total: number;
+    /** Total number of pages */
+    pages: number;
+}
+/**
+ * Response wrapper for paginated list endpoints
+ */
+interface PaginatedResponse<T> {
+    /** Array of items for the current page */
+    data: T[];
+    /** Pagination metadata */
+    pagination: Pagination;
+}
+/**
+ * Response wrapper for single item endpoints
+ */
+interface SingleResponse<T> {
+    /** The requested item */
+    data: T;
+}
+/**
+ * Rate limit information from response headers
+ */
+interface RateLimitInfo {
+    /** Maximum requests allowed per minute */
+    limit: number;
+    /** Remaining requests in the current window */
+    remaining: number;
+    /** Unix timestamp when the rate limit resets */
+    reset: number;
+}
+/**
+ * Extended response that includes rate limit information
+ */
+interface ResponseWithRateLimit<T> {
+    /** The response data */
+    data: T;
+    /** Rate limit information from headers */
+    rateLimit: RateLimitInfo | null;
+}
+/**
+ * Summary information about a COLA (Certificate of Label Approval)
+ * Returned in list/search results
+ */
+interface ColaSummary {
+    /** Unique TTB identifier for this COLA */
+    ttb_id: string;
+    /** Brand name on the label */
+    brand_name: string | null;
+    /** Specific product name */
+    product_name: string | null;
+    /** Type of product (e.g., "DISTILLED SPIRITS", "WINE", "MALT BEVERAGES") */
+    product_type: string | null;
+    /** Product class name */
+    class_name: string | null;
+    /** Origin/country of the product */
+    origin_name: string | null;
+    /** Permit number of the applicant */
+    permit_number: string | null;
+    /** Date the COLA was approved */
+    approval_date: string | null;
+    /** Alcohol by volume percentage */
+    abv: number | null;
+    /** Container volume */
+    volume: string | null;
+    /** Number of images associated with this COLA */
+    image_count: number;
+    /** URL to the main/primary image */
+    main_image_url: string | null;
+}
+/**
+ * Image associated with a COLA
+ */
+interface ColaImage {
+    /** Unique identifier for this image */
+    image_id: string;
+    /** URL to the image */
+    url: string;
+    /** Type of image (e.g., "front", "back") */
+    image_type: string | null;
+    /** Image width in pixels */
+    width: number | null;
+    /** Image height in pixels */
+    height: number | null;
+}
+/**
+ * Barcode found on a COLA label
+ */
+interface ColaBarcode {
+    /** The barcode value/number */
+    barcode_value: string;
+    /** Type of barcode (e.g., "UPC-A", "EAN-13") */
+    barcode_type: string | null;
+}
+/**
+ * Full details for a COLA including images and barcodes
+ */
+interface ColaDetail extends ColaSummary {
+    /** Images associated with this COLA */
+    images: ColaImage[];
+    /** Barcodes found on the label */
+    barcodes: ColaBarcode[];
+    /** LLM-extracted description */
+    llm_description: string | null;
+    /** LLM-extracted ingredients */
+    llm_ingredients: string | null;
+    /** LLM-extracted tasting notes */
+    llm_tasting_notes: string | null;
+    /** LLM-extracted producer/brand information */
+    llm_producer: string | null;
+    /** Vintage year for wines */
+    vintage: number | null;
+    /** Grape varietal(s) */
+    varietal: string | null;
+    /** Wine appellation */
+    appellation: string | null;
+    /** Beer style */
+    beer_style: string | null;
+    /** International Bitterness Units */
+    ibu: number | null;
+    /** Status of the COLA */
+    status: string | null;
+    /** Date the COLA was submitted */
+    submitted_date: string | null;
+    /** Serial number */
+    serial_number: string | null;
+}
+/**
+ * Query parameters for searching/listing COLAs
+ */
+interface ColaListParams {
+    /** Search query string */
+    q?: string;
+    /** Filter by product type */
+    productType?: string;
+    /** Filter by origin/country */
+    origin?: string;
+    /** Filter by brand name */
+    brandName?: string;
+    /** Filter by approval date (from) */
+    approvalDateFrom?: string;
+    /** Filter by approval date (to) */
+    approvalDateTo?: string;
+    /** Minimum ABV percentage */
+    abvMin?: number;
+    /** Maximum ABV percentage */
+    abvMax?: number;
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Items per page */
+    perPage?: number;
+}
+/**
+ * Summary information about a permittee (business/permit holder)
+ */
+interface PermitteeSummary {
+    /** Unique permit number */
+    permit_number: string;
+    /** Company/business name */
+    company_name: string | null;
+    /** State where the company is located */
+    company_state: string | null;
+    /** Type of permit */
+    permittee_type: string | null;
+    /** Whether the permit is currently active */
+    is_active: boolean;
+    /** Total number of COLAs */
+    colas: number;
+    /** Number of approved COLAs */
+    colas_approved: number;
+}
+/**
+ * Full details for a permittee including recent COLAs
+ */
+interface PermitteeDetail extends PermitteeSummary {
+    /** Recent COLAs from this permittee */
+    recent_colas: ColaSummary[];
+}
+/**
+ * Query parameters for searching/listing permittees
+ */
+interface PermitteeListParams {
+    /** Search query string */
+    q?: string;
+    /** Filter by state */
+    state?: string;
+    /** Filter by active status */
+    isActive?: boolean;
+    /** Page number (1-indexed) */
+    page?: number;
+    /** Items per page */
+    perPage?: number;
+}
+/**
+ * Result of a barcode lookup
+ */
+interface BarcodeLookupResult {
+    /** The barcode value that was searched */
+    barcode_value: string;
+    /** Type of barcode */
+    barcode_type: string | null;
+    /** COLAs associated with this barcode */
+    colas: ColaSummary[];
+    /** Total number of COLAs with this barcode */
+    total_colas: number;
+}
+/**
+ * API usage statistics for the current account
+ */
+interface UsageStats {
+    /** Account tier (e.g., "free", "pro", "enterprise") */
+    tier: string;
+    /** Monthly request limit */
+    monthly_limit: number;
+    /** Current billing period (ISO date string) */
+    current_period: string;
+    /** Number of requests used this period */
+    requests_used: number;
+    /** Number of requests remaining this period */
+    requests_remaining: number;
+    /** Per-minute rate limit */
+    per_minute_limit: number;
+}
+/**
+ * Error response structure from the API
+ */
+interface ApiErrorResponse {
+    /** Error message */
+    error: string;
+    /** Error code */
+    code?: string;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+}
+
+/**
+ * COLA Cloud SDK Client
+ */
+
+/**
+ * COLA Cloud API Client
+ *
+ * The main entry point for interacting with the COLA Cloud API.
+ *
+ * @example
+ * ```typescript
+ * import { ColaCloud } from 'colacloud';
+ *
+ * const client = new ColaCloud({ apiKey: 'your-api-key' });
+ *
+ * // Search COLAs
+ * const { data, pagination } = await client.colas.list({ q: 'bourbon' });
+ *
+ * // Get a single COLA
+ * const cola = await client.colas.get('12345678');
+ *
+ * // Iterate all results
+ * for await (const cola of client.colas.iterate({ q: 'whiskey' })) {
+ *   console.log(cola.ttb_id);
+ * }
+ * ```
+ */
+declare class ColaCloud {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    /** COLA (Certificate of Label Approval) endpoints */
+    readonly colas: ColasResource;
+    /** Permittee (business/permit holder) endpoints */
+    readonly permittees: PermitteesResource;
+    /** Barcode lookup endpoint */
+    readonly barcodes: BarcodesResource;
+    /** Usage statistics endpoint */
+    readonly usage: UsageResource;
+    /**
+     * Create a new COLA Cloud API client
+     * @param config Configuration options
+     */
+    constructor(config: ColaCloudConfig);
+    /**
+     * Make an authenticated request to the API
+     * @internal
+     */
+    request<T>(method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, params?: Record<string, unknown>): Promise<ResponseWithRateLimit<T>>;
+    /**
+     * Handle error responses from the API
+     */
+    private handleErrorResponse;
+}
+/**
+ * COLA (Certificate of Label Approval) resource handler
+ */
+declare class ColasResource {
+    private readonly client;
+    constructor(client: ColaCloud);
+    /**
+     * List and search COLAs with pagination
+     * @param params Search and filter parameters
+     * @returns Paginated list of COLA summaries
+     */
+    list(params?: ColaListParams): Promise<PaginatedResponse<ColaSummary>>;
+    /**
+     * List COLAs with rate limit information
+     * @param params Search and filter parameters
+     * @returns Paginated list with rate limit info
+     */
+    listWithRateLimit(params?: ColaListParams): Promise<ResponseWithRateLimit<PaginatedResponse<ColaSummary>>>;
+    /**
+     * Get a single COLA by TTB ID
+     * @param ttbId The unique TTB identifier
+     * @returns Full COLA details including images and barcodes
+     */
+    get(ttbId: string): Promise<ColaDetail>;
+    /**
+     * Get a single COLA with rate limit information
+     * @param ttbId The unique TTB identifier
+     * @returns COLA details with rate limit info
+     */
+    getWithRateLimit(ttbId: string): Promise<ResponseWithRateLimit<ColaDetail>>;
+    /**
+     * Create an async iterator that automatically pages through all results
+     * @param params Search and filter parameters (page is ignored)
+     * @returns Async iterable that yields individual COLA summaries
+     *
+     * @example
+     * ```typescript
+     * for await (const cola of client.colas.iterate({ q: 'bourbon' })) {
+     *   console.log(cola.ttb_id, cola.brand_name);
+     * }
+     * ```
+     */
+    iterate(params?: Omit<ColaListParams, 'page'>): AsyncIterable<ColaSummary>;
+}
+/**
+ * Permittee (business/permit holder) resource handler
+ */
+declare class PermitteesResource {
+    private readonly client;
+    constructor(client: ColaCloud);
+    /**
+     * List and search permittees with pagination
+     * @param params Search and filter parameters
+     * @returns Paginated list of permittee summaries
+     */
+    list(params?: PermitteeListParams): Promise<PaginatedResponse<PermitteeSummary>>;
+    /**
+     * List permittees with rate limit information
+     * @param params Search and filter parameters
+     * @returns Paginated list with rate limit info
+     */
+    listWithRateLimit(params?: PermitteeListParams): Promise<ResponseWithRateLimit<PaginatedResponse<PermitteeSummary>>>;
+    /**
+     * Get a single permittee by permit number
+     * @param permitNumber The unique permit number
+     * @returns Full permittee details including recent COLAs
+     */
+    get(permitNumber: string): Promise<PermitteeDetail>;
+    /**
+     * Get a single permittee with rate limit information
+     * @param permitNumber The unique permit number
+     * @returns Permittee details with rate limit info
+     */
+    getWithRateLimit(permitNumber: string): Promise<ResponseWithRateLimit<PermitteeDetail>>;
+    /**
+     * Create an async iterator that automatically pages through all results
+     * @param params Search and filter parameters (page is ignored)
+     * @returns Async iterable that yields individual permittee summaries
+     *
+     * @example
+     * ```typescript
+     * for await (const permittee of client.permittees.iterate({ state: 'CA' })) {
+     *   console.log(permittee.company_name);
+     * }
+     * ```
+     */
+    iterate(params?: Omit<PermitteeListParams, 'page'>): AsyncIterable<PermitteeSummary>;
+}
+/**
+ * Barcode lookup resource handler
+ */
+declare class BarcodesResource {
+    private readonly client;
+    constructor(client: ColaCloud);
+    /**
+     * Look up COLAs by barcode value
+     * @param barcodeValue The barcode to search for (UPC, EAN, etc.)
+     * @returns Barcode information and associated COLAs
+     */
+    lookup(barcodeValue: string): Promise<BarcodeLookupResult>;
+    /**
+     * Look up barcode with rate limit information
+     * @param barcodeValue The barcode to search for
+     * @returns Barcode lookup result with rate limit info
+     */
+    lookupWithRateLimit(barcodeValue: string): Promise<ResponseWithRateLimit<BarcodeLookupResult>>;
+}
+/**
+ * Usage statistics resource handler
+ */
+declare class UsageResource {
+    private readonly client;
+    constructor(client: ColaCloud);
+    /**
+     * Get API usage statistics for the current account
+     * @returns Usage statistics including limits and current usage
+     */
+    get(): Promise<UsageStats>;
+    /**
+     * Get usage statistics with rate limit information
+     * @returns Usage statistics with rate limit info
+     */
+    getWithRateLimit(): Promise<ResponseWithRateLimit<UsageStats>>;
+}
+
+/**
+ * COLA Cloud SDK Custom Error Classes
+ */
+
+/**
+ * Base error class for all COLA Cloud SDK errors
+ */
+declare class ColaCloudError extends Error {
+    /** HTTP status code (if applicable) */
+    readonly statusCode: number | undefined;
+    /** Error code from the API */
+    readonly code: string | undefined;
+    /** Additional error details */
+    readonly details: Record<string, unknown> | undefined;
+    constructor(message: string, statusCode?: number, code?: string, details?: Record<string, unknown>);
+    /**
+     * Create a ColaCloudError from an API error response
+     */
+    static fromResponse(response: ApiErrorResponse, statusCode: number): ColaCloudError;
+}
+/**
+ * Error thrown when authentication fails (401 Unauthorized)
+ */
+declare class AuthenticationError extends ColaCloudError {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when rate limit is exceeded (429 Too Many Requests)
+ */
+declare class RateLimitError extends ColaCloudError {
+    /** Rate limit information from headers */
+    readonly rateLimit: RateLimitInfo | null;
+    /** Seconds until the rate limit resets */
+    readonly retryAfter: number | null;
+    constructor(message?: string, rateLimit?: RateLimitInfo | null, retryAfter?: number | null);
+}
+/**
+ * Error thrown when a requested resource is not found (404 Not Found)
+ */
+declare class NotFoundError extends ColaCloudError {
+    /** The resource type that was not found */
+    readonly resourceType: string;
+    /** The identifier that was searched for */
+    readonly resourceId: string;
+    constructor(resourceType: string, resourceId: string);
+}
+/**
+ * Error thrown when the request is invalid (400 Bad Request)
+ */
+declare class ValidationError extends ColaCloudError {
+    /** Field-level validation errors */
+    readonly fieldErrors: Record<string, string[]> | undefined;
+    constructor(message?: string, fieldErrors?: Record<string, string[]>);
+}
+/**
+ * Error thrown when the server encounters an error (500+ status codes)
+ */
+declare class ServerError extends ColaCloudError {
+    constructor(message?: string, statusCode?: number);
+}
+/**
+ * Error thrown when a request times out
+ */
+declare class TimeoutError extends ColaCloudError {
+    /** The timeout value in milliseconds */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Error thrown when there's a network connectivity issue
+ */
+declare class NetworkError extends ColaCloudError {
+    /** The original error that caused this */
+    readonly cause: Error | undefined;
+    constructor(message?: string, cause?: Error);
+}
+
+/**
+ * COLA Cloud SDK Pagination Utilities
+ */
+
+/**
+ * Options for creating a paginated iterator
+ */
+interface PaginatedIteratorOptions<TParams> {
+    /** Parameters for the request (excluding page) */
+    params: TParams;
+    /** Function to fetch a page of results */
+    fetchPage: (params: TParams & {
+        page: number;
+    }) => Promise<{
+        response: PaginatedResponse<unknown>;
+        rateLimit: RateLimitInfo | null;
+    }>;
+    /** Starting page number (defaults to 1) */
+    startPage?: number;
+    /** Maximum number of pages to fetch (optional, defaults to all) */
+    maxPages?: number;
+}
+/**
+ * Result yielded by the paginated iterator
+ */
+interface PaginatedIteratorResult<T> {
+    /** The current item */
+    item: T;
+    /** Current page number */
+    page: number;
+    /** Index within the current page */
+    indexInPage: number;
+    /** Total items across all pages */
+    total: number;
+    /** Rate limit info from the last request */
+    rateLimit: RateLimitInfo | null;
+}
+/**
+ * Creates an async iterator that automatically handles pagination
+ * @param options Configuration for the paginated iterator
+ * @returns An async iterable that yields items across all pages
+ */
+declare function createPaginatedIterator<T, TParams>(options: PaginatedIteratorOptions<TParams>): AsyncIterable<T>;
+/**
+ * Creates an async iterator that yields items with additional metadata
+ * @param options Configuration for the paginated iterator
+ * @returns An async iterable that yields items with page/index metadata
+ */
+declare function createPaginatedIteratorWithMetadata<T, TParams>(options: PaginatedIteratorOptions<TParams>): AsyncIterable<PaginatedIteratorResult<T>>;
+/**
+ * Collects all items from a paginated iterator into an array
+ * Warning: Use with caution on large datasets
+ * @param iterator The async iterable to collect from
+ * @param maxItems Maximum number of items to collect (optional safety limit)
+ * @returns Array of all collected items
+ */
+declare function collectAll<T>(iterator: AsyncIterable<T>, maxItems?: number): Promise<T[]>;
+/**
+ * Takes the first N items from a paginated iterator
+ * @param iterator The async iterable to take from
+ * @param count Number of items to take
+ * @returns Array of the first N items
+ */
+declare function take<T>(iterator: AsyncIterable<T>, count: number): Promise<T[]>;
+
+export { type ApiErrorResponse, AuthenticationError, type BarcodeLookupResult, type ColaBarcode, ColaCloud, type ColaCloudConfig, ColaCloudError, type ColaDetail, type ColaImage, type ColaListParams, type ColaSummary, NetworkError, NotFoundError, type PaginatedIteratorOptions, type PaginatedIteratorResult, type PaginatedResponse, type Pagination, type PermitteeDetail, type PermitteeListParams, type PermitteeSummary, RateLimitError, type RateLimitInfo, type ResponseWithRateLimit, ServerError, type SingleResponse, TimeoutError, type UsageStats, ValidationError, collectAll, createPaginatedIterator, createPaginatedIteratorWithMetadata, take };