colacloud 1.0.0

package/dist/index.mjs

@@ -0,0 +1,632 @@
+// src/errors.ts
+var ColaCloudError = class _ColaCloudError extends Error {
+  /** HTTP status code (if applicable) */
+  statusCode;
+  /** Error code from the API */
+  code;
+  /** Additional error details */
+  details;
+  constructor(message, statusCode, code, details) {
+    super(message);
+    this.name = "ColaCloudError";
+    this.statusCode = statusCode;
+    this.code = code;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _ColaCloudError);
+    }
+  }
+  /**
+   * Create a ColaCloudError from an API error response
+   */
+  static fromResponse(response, statusCode) {
+    return new _ColaCloudError(
+      response.error,
+      statusCode,
+      response.code,
+      response.details
+    );
+  }
+};
+var AuthenticationError = class _AuthenticationError extends ColaCloudError {
+  constructor(message = "Invalid or missing API key") {
+    super(message, 401, "authentication_error");
+    this.name = "AuthenticationError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _AuthenticationError);
+    }
+  }
+};
+var RateLimitError = class _RateLimitError extends ColaCloudError {
+  /** Rate limit information from headers */
+  rateLimit;
+  /** Seconds until the rate limit resets */
+  retryAfter;
+  constructor(message = "Rate limit exceeded", rateLimit = null, retryAfter = null) {
+    super(message, 429, "rate_limit_exceeded");
+    this.name = "RateLimitError";
+    this.rateLimit = rateLimit;
+    this.retryAfter = retryAfter;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _RateLimitError);
+    }
+  }
+};
+var NotFoundError = class _NotFoundError extends ColaCloudError {
+  /** The resource type that was not found */
+  resourceType;
+  /** The identifier that was searched for */
+  resourceId;
+  constructor(resourceType, resourceId) {
+    super(`${resourceType} not found: ${resourceId}`, 404, "not_found");
+    this.name = "NotFoundError";
+    this.resourceType = resourceType;
+    this.resourceId = resourceId;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _NotFoundError);
+    }
+  }
+};
+var ValidationError = class _ValidationError extends ColaCloudError {
+  /** Field-level validation errors */
+  fieldErrors;
+  constructor(message = "Invalid request parameters", fieldErrors) {
+    super(message, 400, "validation_error", fieldErrors);
+    this.name = "ValidationError";
+    this.fieldErrors = fieldErrors;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _ValidationError);
+    }
+  }
+};
+var ServerError = class _ServerError extends ColaCloudError {
+  constructor(message = "Internal server error", statusCode = 500) {
+    super(message, statusCode, "server_error");
+    this.name = "ServerError";
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _ServerError);
+    }
+  }
+};
+var TimeoutError = class _TimeoutError extends ColaCloudError {
+  /** The timeout value in milliseconds */
+  timeoutMs;
+  constructor(timeoutMs) {
+    super(`Request timed out after ${timeoutMs}ms`, void 0, "timeout");
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _TimeoutError);
+    }
+  }
+};
+var NetworkError = class _NetworkError extends ColaCloudError {
+  /** The original error that caused this */
+  cause;
+  constructor(message = "Network error", cause) {
+    super(message, void 0, "network_error");
+    this.name = "NetworkError";
+    this.cause = cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _NetworkError);
+    }
+  }
+};
+
+// src/pagination.ts
+function createPaginatedIterator(options) {
+  const { params, fetchPage, startPage = 1, maxPages } = options;
+  return {
+    [Symbol.asyncIterator]() {
+      let currentPage = startPage;
+      let currentItems = [];
+      let currentIndex = 0;
+      let pagination = null;
+      let pagesFetched = 0;
+      let done = false;
+      return {
+        async next() {
+          while (currentIndex >= currentItems.length && !done) {
+            if (maxPages !== void 0 && pagesFetched >= maxPages) {
+              done = true;
+              break;
+            }
+            if (pagination !== null && currentPage > pagination.pages) {
+              done = true;
+              break;
+            }
+            const result = await fetchPage({
+              ...params,
+              page: currentPage
+            });
+            pagination = result.response.pagination;
+            currentItems = result.response.data;
+            currentIndex = 0;
+            currentPage++;
+            pagesFetched++;
+            if (currentItems.length === 0) {
+              done = true;
+              break;
+            }
+          }
+          if (currentIndex < currentItems.length) {
+            const item = currentItems[currentIndex];
+            currentIndex++;
+            if (item === void 0) {
+              return { done: true, value: void 0 };
+            }
+            return { done: false, value: item };
+          }
+          return { done: true, value: void 0 };
+        }
+      };
+    }
+  };
+}
+function createPaginatedIteratorWithMetadata(options) {
+  const { params, fetchPage, startPage = 1, maxPages } = options;
+  return {
+    [Symbol.asyncIterator]() {
+      let currentPage = startPage;
+      let currentItems = [];
+      let currentIndex = 0;
+      let pagination = null;
+      let rateLimit = null;
+      let pagesFetched = 0;
+      let done = false;
+      return {
+        async next() {
+          while (currentIndex >= currentItems.length && !done) {
+            if (maxPages !== void 0 && pagesFetched >= maxPages) {
+              done = true;
+              break;
+            }
+            if (pagination !== null && currentPage > pagination.pages) {
+              done = true;
+              break;
+            }
+            const result = await fetchPage({
+              ...params,
+              page: currentPage
+            });
+            pagination = result.response.pagination;
+            rateLimit = result.rateLimit;
+            currentItems = result.response.data;
+            currentIndex = 0;
+            currentPage++;
+            pagesFetched++;
+            if (currentItems.length === 0) {
+              done = true;
+              break;
+            }
+          }
+          if (currentIndex < currentItems.length) {
+            const item = currentItems[currentIndex];
+            if (item === void 0) {
+              return { done: true, value: void 0 };
+            }
+            const result = {
+              item,
+              page: currentPage - 1,
+              // We already incremented after fetch
+              indexInPage: currentIndex,
+              total: pagination?.total ?? 0,
+              rateLimit
+            };
+            currentIndex++;
+            return { done: false, value: result };
+          }
+          return { done: true, value: void 0 };
+        }
+      };
+    }
+  };
+}
+async function collectAll(iterator, maxItems) {
+  const items = [];
+  for await (const item of iterator) {
+    items.push(item);
+    if (maxItems !== void 0 && items.length >= maxItems) {
+      break;
+    }
+  }
+  return items;
+}
+async function take(iterator, count) {
+  return collectAll(iterator, count);
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://app.colacloud.us/api/v1";
+var DEFAULT_TIMEOUT = 3e4;
+function toSnakeCase(params) {
+  const result = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    const snakeKey = key.replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+    result[snakeKey] = String(value);
+  }
+  return result;
+}
+function parseRateLimitHeaders(headers) {
+  const limit = headers.get("X-RateLimit-Limit");
+  const remaining = headers.get("X-RateLimit-Remaining");
+  const reset = headers.get("X-RateLimit-Reset");
+  if (limit === null || remaining === null || reset === null) {
+    return null;
+  }
+  return {
+    limit: parseInt(limit, 10),
+    remaining: parseInt(remaining, 10),
+    reset: parseInt(reset, 10)
+  };
+}
+var ColaCloud = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  /** COLA (Certificate of Label Approval) endpoints */
+  colas;
+  /** Permittee (business/permit holder) endpoints */
+  permittees;
+  /** Barcode lookup endpoint */
+  barcodes;
+  /** Usage statistics endpoint */
+  usage;
+  /**
+   * Create a new COLA Cloud API client
+   * @param config Configuration options
+   */
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.colas = new ColasResource(this);
+    this.permittees = new PermitteesResource(this);
+    this.barcodes = new BarcodesResource(this);
+    this.usage = new UsageResource(this);
+  }
+  /**
+   * Make an authenticated request to the API
+   * @internal
+   */
+  async request(method, path, params) {
+    let url = `${this.baseUrl}${path}`;
+    if (method === "GET" && params && Object.keys(params).length > 0) {
+      const searchParams = new URLSearchParams(toSnakeCase(params));
+      url += `?${searchParams.toString()}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          "X-API-Key": this.apiKey,
+          "Content-Type": "application/json",
+          Accept: "application/json"
+        },
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      const rateLimit = parseRateLimitHeaders(response.headers);
+      if (!response.ok) {
+        await this.handleErrorResponse(response, rateLimit);
+      }
+      const data = await response.json();
+      return { data, rateLimit };
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new TimeoutError(this.timeout);
+      }
+      if (error instanceof ColaCloudError) {
+        throw error;
+      }
+      throw new NetworkError(
+        error instanceof Error ? error.message : "Unknown error",
+        error instanceof Error ? error : void 0
+      );
+    }
+  }
+  /**
+   * Handle error responses from the API
+   */
+  async handleErrorResponse(response, rateLimit) {
+    let errorData;
+    try {
+      errorData = await response.json();
+    } catch {
+      errorData = { error: response.statusText || "Unknown error" };
+    }
+    const message = errorData.error || "Unknown error";
+    switch (response.status) {
+      case 401:
+        throw new AuthenticationError(message);
+      case 404:
+        throw new NotFoundError("Resource", "unknown");
+      case 429: {
+        const retryAfter = response.headers.get("Retry-After");
+        throw new RateLimitError(
+          message,
+          rateLimit,
+          retryAfter ? parseInt(retryAfter, 10) : null
+        );
+      }
+      case 400:
+        throw new ValidationError(
+          message,
+          errorData.details
+        );
+      default:
+        if (response.status >= 500) {
+          throw new ServerError(message, response.status);
+        }
+        throw ColaCloudError.fromResponse(errorData, response.status);
+    }
+  }
+};
+var ColasResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List and search COLAs with pagination
+   * @param params Search and filter parameters
+   * @returns Paginated list of COLA summaries
+   */
+  async list(params = {}) {
+    const result = await this.client.request(
+      "GET",
+      "/colas",
+      params
+    );
+    return result.data;
+  }
+  /**
+   * List COLAs with rate limit information
+   * @param params Search and filter parameters
+   * @returns Paginated list with rate limit info
+   */
+  async listWithRateLimit(params = {}) {
+    return this.client.request(
+      "GET",
+      "/colas",
+      params
+    );
+  }
+  /**
+   * Get a single COLA by TTB ID
+   * @param ttbId The unique TTB identifier
+   * @returns Full COLA details including images and barcodes
+   */
+  async get(ttbId) {
+    try {
+      const result = await this.client.request(
+        "GET",
+        `/colas/${encodeURIComponent(ttbId)}`
+      );
+      return result.data.data;
+    } catch (error) {
+      if (error instanceof NotFoundError) {
+        throw new NotFoundError("COLA", ttbId);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Get a single COLA with rate limit information
+   * @param ttbId The unique TTB identifier
+   * @returns COLA details with rate limit info
+   */
+  async getWithRateLimit(ttbId) {
+    try {
+      const result = await this.client.request(
+        "GET",
+        `/colas/${encodeURIComponent(ttbId)}`
+      );
+      return { data: result.data.data, rateLimit: result.rateLimit };
+    } catch (error) {
+      if (error instanceof NotFoundError) {
+        throw new NotFoundError("COLA", ttbId);
+      }
+      throw error;
+    }
+  }
+  /**
+   * 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 = {}) {
+    return createPaginatedIterator({
+      params,
+      fetchPage: async (p) => {
+        const result = await this.client.request(
+          "GET",
+          "/colas",
+          p
+        );
+        return { response: result.data, rateLimit: result.rateLimit };
+      }
+    });
+  }
+};
+var PermitteesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List and search permittees with pagination
+   * @param params Search and filter parameters
+   * @returns Paginated list of permittee summaries
+   */
+  async list(params = {}) {
+    const result = await this.client.request(
+      "GET",
+      "/permittees",
+      params
+    );
+    return result.data;
+  }
+  /**
+   * List permittees with rate limit information
+   * @param params Search and filter parameters
+   * @returns Paginated list with rate limit info
+   */
+  async listWithRateLimit(params = {}) {
+    return this.client.request(
+      "GET",
+      "/permittees",
+      params
+    );
+  }
+  /**
+   * Get a single permittee by permit number
+   * @param permitNumber The unique permit number
+   * @returns Full permittee details including recent COLAs
+   */
+  async get(permitNumber) {
+    try {
+      const result = await this.client.request(
+        "GET",
+        `/permittees/${encodeURIComponent(permitNumber)}`
+      );
+      return result.data.data;
+    } catch (error) {
+      if (error instanceof NotFoundError) {
+        throw new NotFoundError("Permittee", permitNumber);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Get a single permittee with rate limit information
+   * @param permitNumber The unique permit number
+   * @returns Permittee details with rate limit info
+   */
+  async getWithRateLimit(permitNumber) {
+    try {
+      const result = await this.client.request(
+        "GET",
+        `/permittees/${encodeURIComponent(permitNumber)}`
+      );
+      return { data: result.data.data, rateLimit: result.rateLimit };
+    } catch (error) {
+      if (error instanceof NotFoundError) {
+        throw new NotFoundError("Permittee", permitNumber);
+      }
+      throw error;
+    }
+  }
+  /**
+   * 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 = {}) {
+    return createPaginatedIterator({
+      params,
+      fetchPage: async (p) => {
+        const result = await this.client.request("GET", "/permittees", p);
+        return { response: result.data, rateLimit: result.rateLimit };
+      }
+    });
+  }
+};
+var BarcodesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Look up COLAs by barcode value
+   * @param barcodeValue The barcode to search for (UPC, EAN, etc.)
+   * @returns Barcode information and associated COLAs
+   */
+  async lookup(barcodeValue) {
+    try {
+      const result = await this.client.request("GET", `/barcode/${encodeURIComponent(barcodeValue)}`);
+      return result.data.data;
+    } catch (error) {
+      if (error instanceof NotFoundError) {
+        throw new NotFoundError("Barcode", barcodeValue);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Look up barcode with rate limit information
+   * @param barcodeValue The barcode to search for
+   * @returns Barcode lookup result with rate limit info
+   */
+  async lookupWithRateLimit(barcodeValue) {
+    try {
+      const result = await this.client.request("GET", `/barcode/${encodeURIComponent(barcodeValue)}`);
+      return { data: result.data.data, rateLimit: result.rateLimit };
+    } catch (error) {
+      if (error instanceof NotFoundError) {
+        throw new NotFoundError("Barcode", barcodeValue);
+      }
+      throw error;
+    }
+  }
+};
+var UsageResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get API usage statistics for the current account
+   * @returns Usage statistics including limits and current usage
+   */
+  async get() {
+    const result = await this.client.request(
+      "GET",
+      "/usage"
+    );
+    return result.data.data;
+  }
+  /**
+   * Get usage statistics with rate limit information
+   * @returns Usage statistics with rate limit info
+   */
+  async getWithRateLimit() {
+    const result = await this.client.request(
+      "GET",
+      "/usage"
+    );
+    return { data: result.data.data, rateLimit: result.rateLimit };
+  }
+};
+export {
+  AuthenticationError,
+  ColaCloud,
+  ColaCloudError,
+  NetworkError,
+  NotFoundError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  ValidationError,
+  collectAll,
+  createPaginatedIterator,
+  createPaginatedIteratorWithMetadata,
+  take
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "colacloud",
+  "version": "1.0.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",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src tests --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "cola",
+    "ttb",
+    "alcohol",
+    "beverage",
+    "label",
+    "api",
+    "sdk",
+    "typescript"
+  ],
+  "author": "COLA Cloud",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cola-cloud-us/colacloud-js.git"
+  },
+  "homepage": "https://colacloud.us",
+  "bugs": {
+    "url": "https://github.com/cola-cloud-us/colacloud-js/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.0",
+    "vitest": "^1.1.0"
+  }
+}