colacloud 1.0.0 → 1.2.0

package/README.md

@@ -165,9 +165,10 @@ for (const cola of result.colas) {
 const usage = await client.usage.get();
 
 console.log(`Tier: ${usage.tier}`);
-console.log(`Used: ${usage.requests_used} / ${usage.monthly_limit}`);
-console.log(`Remaining: ${usage.requests_remaining}`);
-console.log(`Rate limit: ${usage.per_minute_limit} req/min`);
+console.log(`Period: ${usage.current_period}`);
+console.log(`Detail views: ${usage.detail_views.used} / ${usage.detail_views.limit}`);
+console.log(`List records: ${usage.list_records.used} / ${usage.list_records.limit}`);
+console.log(`Burst limit: ${usage.per_minute_limit} req/min`);
 ```
 
 ### Rate Limit Information

package/dist/index.d.mts

@@ -80,73 +80,133 @@ interface ColaSummary {
     origin_name: string | null;
     /** Permit number of the applicant */
     permit_number: string | null;
-    /** Date the COLA was approved */
+    /** Date the COLA was approved (ISO date string) */
     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;
+    /** Whether any barcode was extracted from label images */
+    has_barcode: boolean;
 }
 /**
  * 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;
+    /** Unique TTB image identifier */
+    ttb_image_id: string;
+    /** Position of image within the COLA's image set (0-indexed) */
+    image_index: number;
+    /** Position on the container (e.g., "FRONT", "BACK", "NECK", "STRIP") */
+    container_position: string | null;
+    /** File extension (e.g., "jpg", "png") */
+    extension_type: string | null;
     /** Image width in pixels */
-    width: number | null;
+    width_pixels: number | null;
     /** Image height in pixels */
-    height: number | null;
+    height_pixels: number | null;
+    /** Physical label width in inches */
+    width_inches: number | null;
+    /** Physical label height in inches */
+    height_inches: number | null;
+    /** File size in megabytes */
+    file_size_mb: number | null;
+    /** Number of barcodes detected in this image */
+    barcode_count: number;
+    /** Number of QR codes detected in this image */
+    qrcode_count: number;
+    /** Signed URL to the image (when available) */
+    image_url?: string;
 }
 /**
  * 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;
+    /** The barcode value/number */
+    barcode_value: string;
+    /** TTB image ID where this barcode was found */
+    ttb_image_id: string;
+    /** Barcode width in pixels */
+    width_pixels: number | null;
+    /** Barcode height in pixels */
+    height_pixels: number | null;
+    /** Barcode orientation (e.g., "horizontal", "vertical") */
+    orientation: string | null;
+    /** Position of the barcode relative to the image */
+    relative_image_position: string | null;
 }
 /**
  * Full details for a COLA including images and barcodes
  */
 interface ColaDetail extends ColaSummary {
-    /** Images associated with this COLA */
+    /** Product class ID */
+    class_id: string | null;
+    /** Origin ID */
+    origin_id: string | null;
+    /** Date of the most recent update (ISO date string) */
+    latest_update_date: string | null;
+    /** Whether the container has a distinctive shape */
+    is_distinctive_container: boolean | null;
+    /** Distinctive container capacity */
+    for_distinctive_capacity: string | null;
+    /** Whether this is a resubmission */
+    is_resubmission: boolean | null;
+    /** TTB ID of the original submission if this is a resubmission */
+    for_resubmission_ttb_id: string | null;
+    /** State exemption, if applicable */
+    for_exemption_state: string | null;
+    /** Applicant address recipient */
+    address_recipient: string | null;
+    /** Applicant ZIP code */
+    address_zip_code: string | null;
+    /** Applicant state */
+    address_state: string | null;
+    /** Grape varietals (wine) */
+    grape_varietals: string | null;
+    /** Vintage year (wine) */
+    wine_vintage_year: number | null;
+    /** Appellation (wine) */
+    wine_appellation: string | null;
+    /** LLM-extracted container type */
+    llm_container_type: string | null;
+    /** LLM-extracted product description */
+    llm_product_description: string | null;
+    /** LLM-extracted brand established year */
+    llm_brand_established_year: number | null;
+    /** LLM-extracted tasting note flavors */
+    llm_tasting_note_flavors: string | null;
+    /** LLM-extracted artwork credit */
+    llm_artwork_credit: string | null;
+    /** LLM-extracted wine designation */
+    llm_wine_designation: string | null;
+    /** LLM-extracted International Bitterness Units (beer) */
+    llm_beer_ibu: number | null;
+    /** LLM-extracted hop varieties (beer) */
+    llm_beer_hops_varieties: string | null;
+    /** LLM-extracted aged years (liquor) */
+    llm_liquor_aged_years: number | null;
+    /** LLM-extracted finishing process (liquor) */
+    llm_liquor_finishing_process: string | null;
+    /** LLM-extracted grains used (liquor) */
+    llm_liquor_grains: string | null;
+    /** Primary barcode type on this COLA */
+    barcode_type: string | null;
+    /** Primary barcode value on this COLA */
+    barcode_value: string | null;
+    /** QR code URL if present */
+    qrcode_url: string | null;
+    /** Whether a front label image exists */
+    has_front_image: boolean;
+    /** Whether a back label image exists */
+    has_back_image: boolean;
+    /** Whether a neck label image exists */
+    has_neck_image: boolean;
+    /** Whether a strip label image exists */
+    has_strip_image: boolean;
+    /** All images associated with this COLA */
     images: ColaImage[];
-    /** Barcodes found on the label */
+    /** All barcodes found on this COLA's images */
     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
@@ -183,14 +243,20 @@ interface PermitteeSummary {
     company_name: string | null;
     /** State where the company is located */
     company_state: string | null;
+    /** Company ZIP code */
+    company_zip_code: string | null;
     /** Type of permit */
     permittee_type: string | null;
     /** Whether the permit is currently active */
     is_active: boolean;
+    /** Reason for active/inactive status */
+    active_reason: string | null;
     /** Total number of COLAs */
     colas: number;
     /** Number of approved COLAs */
     colas_approved: number;
+    /** Date of most recent COLA application (ISO date string) */
+    last_cola_application_date: string | null;
 }
 /**
  * Full details for a permittee including recent COLAs
@@ -227,21 +293,33 @@ interface BarcodeLookupResult {
     /** Total number of COLAs with this barcode */
     total_colas: number;
 }
+/**
+ * API usage statistics for the current account
+ */
+/**
+ * Usage quota for a single meter (detail views or list records)
+ */
+interface UsageQuota {
+    /** Number used this period */
+    used: number;
+    /** Maximum allowed this period */
+    limit: number;
+    /** Remaining this period */
+    remaining: number;
+}
 /**
  * API usage statistics for the current account
  */
 interface UsageStats {
-    /** Account tier (e.g., "free", "pro", "enterprise") */
+    /** Account tier (e.g., "free", "starter", "pro") */
     tier: string;
-    /** Monthly request limit */
-    monthly_limit: number;
-    /** Current billing period (ISO date string) */
+    /** Current billing period (YYYY-MM) */
     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 */
+    /** Detail view usage and limits */
+    detail_views: UsageQuota;
+    /** List record usage and limits */
+    list_records: UsageQuota;
+    /** Per-minute burst limit */
     per_minute_limit: number;
 }
 /**

package/dist/index.d.ts

@@ -80,73 +80,133 @@ interface ColaSummary {
     origin_name: string | null;
     /** Permit number of the applicant */
     permit_number: string | null;
-    /** Date the COLA was approved */
+    /** Date the COLA was approved (ISO date string) */
     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;
+    /** Whether any barcode was extracted from label images */
+    has_barcode: boolean;
 }
 /**
  * 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;
+    /** Unique TTB image identifier */
+    ttb_image_id: string;
+    /** Position of image within the COLA's image set (0-indexed) */
+    image_index: number;
+    /** Position on the container (e.g., "FRONT", "BACK", "NECK", "STRIP") */
+    container_position: string | null;
+    /** File extension (e.g., "jpg", "png") */
+    extension_type: string | null;
     /** Image width in pixels */
-    width: number | null;
+    width_pixels: number | null;
     /** Image height in pixels */
-    height: number | null;
+    height_pixels: number | null;
+    /** Physical label width in inches */
+    width_inches: number | null;
+    /** Physical label height in inches */
+    height_inches: number | null;
+    /** File size in megabytes */
+    file_size_mb: number | null;
+    /** Number of barcodes detected in this image */
+    barcode_count: number;
+    /** Number of QR codes detected in this image */
+    qrcode_count: number;
+    /** Signed URL to the image (when available) */
+    image_url?: string;
 }
 /**
  * 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;
+    /** The barcode value/number */
+    barcode_value: string;
+    /** TTB image ID where this barcode was found */
+    ttb_image_id: string;
+    /** Barcode width in pixels */
+    width_pixels: number | null;
+    /** Barcode height in pixels */
+    height_pixels: number | null;
+    /** Barcode orientation (e.g., "horizontal", "vertical") */
+    orientation: string | null;
+    /** Position of the barcode relative to the image */
+    relative_image_position: string | null;
 }
 /**
  * Full details for a COLA including images and barcodes
  */
 interface ColaDetail extends ColaSummary {
-    /** Images associated with this COLA */
+    /** Product class ID */
+    class_id: string | null;
+    /** Origin ID */
+    origin_id: string | null;
+    /** Date of the most recent update (ISO date string) */
+    latest_update_date: string | null;
+    /** Whether the container has a distinctive shape */
+    is_distinctive_container: boolean | null;
+    /** Distinctive container capacity */
+    for_distinctive_capacity: string | null;
+    /** Whether this is a resubmission */
+    is_resubmission: boolean | null;
+    /** TTB ID of the original submission if this is a resubmission */
+    for_resubmission_ttb_id: string | null;
+    /** State exemption, if applicable */
+    for_exemption_state: string | null;
+    /** Applicant address recipient */
+    address_recipient: string | null;
+    /** Applicant ZIP code */
+    address_zip_code: string | null;
+    /** Applicant state */
+    address_state: string | null;
+    /** Grape varietals (wine) */
+    grape_varietals: string | null;
+    /** Vintage year (wine) */
+    wine_vintage_year: number | null;
+    /** Appellation (wine) */
+    wine_appellation: string | null;
+    /** LLM-extracted container type */
+    llm_container_type: string | null;
+    /** LLM-extracted product description */
+    llm_product_description: string | null;
+    /** LLM-extracted brand established year */
+    llm_brand_established_year: number | null;
+    /** LLM-extracted tasting note flavors */
+    llm_tasting_note_flavors: string | null;
+    /** LLM-extracted artwork credit */
+    llm_artwork_credit: string | null;
+    /** LLM-extracted wine designation */
+    llm_wine_designation: string | null;
+    /** LLM-extracted International Bitterness Units (beer) */
+    llm_beer_ibu: number | null;
+    /** LLM-extracted hop varieties (beer) */
+    llm_beer_hops_varieties: string | null;
+    /** LLM-extracted aged years (liquor) */
+    llm_liquor_aged_years: number | null;
+    /** LLM-extracted finishing process (liquor) */
+    llm_liquor_finishing_process: string | null;
+    /** LLM-extracted grains used (liquor) */
+    llm_liquor_grains: string | null;
+    /** Primary barcode type on this COLA */
+    barcode_type: string | null;
+    /** Primary barcode value on this COLA */
+    barcode_value: string | null;
+    /** QR code URL if present */
+    qrcode_url: string | null;
+    /** Whether a front label image exists */
+    has_front_image: boolean;
+    /** Whether a back label image exists */
+    has_back_image: boolean;
+    /** Whether a neck label image exists */
+    has_neck_image: boolean;
+    /** Whether a strip label image exists */
+    has_strip_image: boolean;
+    /** All images associated with this COLA */
     images: ColaImage[];
-    /** Barcodes found on the label */
+    /** All barcodes found on this COLA's images */
     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
@@ -183,14 +243,20 @@ interface PermitteeSummary {
     company_name: string | null;
     /** State where the company is located */
     company_state: string | null;
+    /** Company ZIP code */
+    company_zip_code: string | null;
     /** Type of permit */
     permittee_type: string | null;
     /** Whether the permit is currently active */
     is_active: boolean;
+    /** Reason for active/inactive status */
+    active_reason: string | null;
     /** Total number of COLAs */
     colas: number;
     /** Number of approved COLAs */
     colas_approved: number;
+    /** Date of most recent COLA application (ISO date string) */
+    last_cola_application_date: string | null;
 }
 /**
  * Full details for a permittee including recent COLAs
@@ -227,21 +293,33 @@ interface BarcodeLookupResult {
     /** Total number of COLAs with this barcode */
     total_colas: number;
 }
+/**
+ * API usage statistics for the current account
+ */
+/**
+ * Usage quota for a single meter (detail views or list records)
+ */
+interface UsageQuota {
+    /** Number used this period */
+    used: number;
+    /** Maximum allowed this period */
+    limit: number;
+    /** Remaining this period */
+    remaining: number;
+}
 /**
  * API usage statistics for the current account
  */
 interface UsageStats {
-    /** Account tier (e.g., "free", "pro", "enterprise") */
+    /** Account tier (e.g., "free", "starter", "pro") */
     tier: string;
-    /** Monthly request limit */
-    monthly_limit: number;
-    /** Current billing period (ISO date string) */
+    /** Current billing period (YYYY-MM) */
     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 */
+    /** Detail view usage and limits */
+    detail_views: UsageQuota;
+    /** List record usage and limits */
+    list_records: UsageQuota;
+    /** Per-minute burst limit */
     per_minute_limit: number;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "colacloud",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Official JavaScript/TypeScript SDK for the COLA Cloud API - access the TTB COLA Registry of alcohol product label approvals",
   "main": "dist/index.js",
   "module": "dist/index.mjs",