@ontos-ai/knowhere-sdk 0.2.0

package/dist/index.js

@@ -0,0 +1,1245 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  APIError: () => APIError,
+  AuthenticationError: () => AuthenticationError,
+  BadRequestError: () => BadRequestError,
+  ChecksumError: () => ChecksumError,
+  ConflictError: () => ConflictError,
+  GatewayTimeoutError: () => GatewayTimeoutError,
+  InternalServerError: () => InternalServerError,
+  InvalidStateError: () => InvalidStateError,
+  JobFailedError: () => JobFailedError,
+  Jobs: () => Jobs,
+  Knowhere: () => Knowhere,
+  KnowhereError: () => KnowhereError,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  PaymentRequiredError: () => PaymentRequiredError,
+  PermissionDeniedError: () => PermissionDeniedError,
+  PollingTimeoutError: () => PollingTimeoutError,
+  RateLimitError: () => RateLimitError,
+  ServiceUnavailableError: () => ServiceUnavailableError,
+  TimeoutError: () => TimeoutError,
+  VERSION: () => VERSION,
+  ValidationError: () => ValidationError,
+  default: () => Knowhere
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_path2 = __toESM(require("path"));
+
+// src/lib/http-client.ts
+var import_axios = __toESM(require("axios"));
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/constants.ts
+var DEFAULT_BASE_URL = "https://api.knowhereto.ai";
+var DEFAULT_TIMEOUT = 6e4;
+var DEFAULT_MAX_RETRIES = 5;
+var DEFAULT_POLL_INTERVAL = 1e4;
+var MAX_POLL_INTERVAL = 3e4;
+var DEFAULT_POLL_TIMEOUT = 18e5;
+var POLL_INTERVAL_INCREASE_THRESHOLD = 6e4;
+var POLL_INTERVAL_MULTIPLIER = 1.2;
+var INITIAL_RETRY_DELAY = 500;
+var MAX_RETRY_DELAY = 3e4;
+var RETRY_DELAY_BASE = 2;
+var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([409, 429, 502, 503, 504]);
+var TERMINAL_JOB_STATUSES = /* @__PURE__ */ new Set(["done", "failed"]);
+var ENV = {
+  API_KEY: "KNOWHERE_API_KEY",
+  BASE_URL: "KNOWHERE_BASE_URL",
+  LOG_LEVEL: "KNOWHERE_LOG_LEVEL"
+};
+
+// src/errors/base.ts
+var KnowhereError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "KnowhereError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var NetworkError = class extends KnowhereError {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "NetworkError";
+  }
+};
+var TimeoutError = class extends NetworkError {
+  constructor(message = "Request timed out") {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+var PollingTimeoutError = class extends KnowhereError {
+  constructor(message = "Polling timed out", elapsedMs) {
+    super(message);
+    this.elapsedMs = elapsedMs;
+    this.name = "PollingTimeoutError";
+  }
+};
+var ChecksumError = class extends KnowhereError {
+  constructor(message = "Checksum verification failed", expected, actual) {
+    super(message);
+    this.expected = expected;
+    this.actual = actual;
+    this.name = "ChecksumError";
+  }
+};
+var ValidationError = class extends KnowhereError {
+  constructor(message) {
+    super(message);
+    this.name = "ValidationError";
+  }
+};
+var InvalidStateError = class extends KnowhereError {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidStateError";
+  }
+};
+
+// src/errors/api-errors.ts
+var APIError = class extends KnowhereError {
+  constructor(message, statusCode, code, requestId, details, body) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.requestId = requestId;
+    this.details = details;
+    this.body = body;
+    this.name = "APIError";
+  }
+};
+var BadRequestError = class extends APIError {
+  constructor(message, code, requestId, details, body) {
+    super(message, 400, code, requestId, details, body);
+    this.name = "BadRequestError";
+  }
+};
+var AuthenticationError = class extends APIError {
+  constructor(message = "Authentication failed", code, requestId, details, body) {
+    super(message, 401, code, requestId, details, body);
+    this.name = "AuthenticationError";
+  }
+};
+var PaymentRequiredError = class extends APIError {
+  constructor(message = "Payment required", code, requestId, details, body) {
+    super(message, 402, code, requestId, details, body);
+    this.name = "PaymentRequiredError";
+  }
+};
+var PermissionDeniedError = class extends APIError {
+  constructor(message = "Permission denied", code, requestId, details, body) {
+    super(message, 403, code, requestId, details, body);
+    this.name = "PermissionDeniedError";
+  }
+};
+var NotFoundError = class extends APIError {
+  constructor(message = "Resource not found", code, requestId, details, body) {
+    super(message, 404, code, requestId, details, body);
+    this.name = "NotFoundError";
+  }
+};
+var ConflictError = class extends APIError {
+  constructor(message = "Conflict", code, requestId, details, body) {
+    super(message, 409, code, requestId, details, body);
+    this.name = "ConflictError";
+  }
+};
+var RateLimitError = class extends APIError {
+  constructor(message = "Rate limit exceeded", code, requestId, details, body, retryAfter) {
+    super(message, 429, code, requestId, details, body);
+    this.retryAfter = retryAfter;
+    this.name = "RateLimitError";
+  }
+};
+var InternalServerError = class extends APIError {
+  constructor(message = "Internal server error", code, requestId, details, body) {
+    super(message, 500, code, requestId, details, body);
+    this.name = "InternalServerError";
+  }
+};
+var ServiceUnavailableError = class extends APIError {
+  constructor(message = "Service unavailable", statusCode = 503, code, requestId, details, body) {
+    super(message, statusCode, code, requestId, details, body);
+    this.name = "ServiceUnavailableError";
+  }
+};
+var GatewayTimeoutError = class extends APIError {
+  constructor(message = "Gateway timeout", code, requestId, details, body) {
+    super(message, 504, code, requestId, details, body);
+    this.name = "GatewayTimeoutError";
+  }
+};
+function createAPIError(statusCode, message, code, requestId, details, body, retryAfter) {
+  switch (statusCode) {
+    case 400:
+      return new BadRequestError(message, code, requestId, details, body);
+    case 401:
+      return new AuthenticationError(message, code, requestId, details, body);
+    case 402:
+      return new PaymentRequiredError(message, code, requestId, details, body);
+    case 403:
+      return new PermissionDeniedError(message, code, requestId, details, body);
+    case 404:
+      return new NotFoundError(message, code, requestId, details, body);
+    case 409:
+      return new ConflictError(message, code, requestId, details, body);
+    case 429:
+      return new RateLimitError(message, code, requestId, details, body, retryAfter);
+    case 500:
+      return new InternalServerError(message, code, requestId, details, body);
+    case 502:
+    case 503:
+      return new ServiceUnavailableError(message, statusCode, code, requestId, details, body);
+    case 504:
+      return new GatewayTimeoutError(message, code, requestId, details, body);
+    default:
+      return new APIError(message, statusCode, code, requestId, details, body);
+  }
+}
+
+// src/errors/job-errors.ts
+var JobFailedError = class extends KnowhereError {
+  constructor(message, code, jobResult) {
+    super(message);
+    this.code = code;
+    this.jobResult = jobResult;
+    this.name = "JobFailedError";
+  }
+};
+
+// src/lib/utils.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function snakeToCamel(str) {
+  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function camelToSnake(str) {
+  return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+function keysToCamel(obj) {
+  if (obj === null || obj === void 0) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => keysToCamel(item));
+  }
+  if (typeof obj === "object" && obj.constructor === Object) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[snakeToCamel(key)] = keysToCamel(value);
+    }
+    return result;
+  }
+  return obj;
+}
+function keysToSnake(obj) {
+  if (obj === null || obj === void 0) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => keysToSnake(item));
+  }
+  if (typeof obj === "object" && obj.constructor === Object) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      result[camelToSnake(key)] = keysToSnake(value);
+    }
+    return result;
+  }
+  return obj;
+}
+function parseDates(obj) {
+  if (obj === null || obj === void 0) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => parseDates(item));
+  }
+  if (typeof obj === "object" && obj.constructor === Object) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      if ((key.endsWith("At") || key.endsWith("Date")) && typeof value === "string" && /^\d{4}-\d{2}-\d{2}T/.test(value)) {
+        result[key] = new Date(value);
+      } else {
+        result[key] = parseDates(value);
+      }
+    }
+    return result;
+  }
+  return obj;
+}
+function isTerminalStatus(status) {
+  return TERMINAL_JOB_STATUSES.has(status);
+}
+function enrichJobResult(jobResult) {
+  const computedProperties = {};
+  if (!Object.getOwnPropertyDescriptor(jobResult, "isTerminal")) {
+    computedProperties.isTerminal = {
+      get() {
+        return isTerminalStatus(this.status);
+      },
+      enumerable: true,
+      configurable: true
+    };
+  }
+  if (!Object.getOwnPropertyDescriptor(jobResult, "isDone")) {
+    computedProperties.isDone = {
+      get() {
+        return this.status === "done";
+      },
+      enumerable: true,
+      configurable: true
+    };
+  }
+  if (!Object.getOwnPropertyDescriptor(jobResult, "isFailed")) {
+    computedProperties.isFailed = {
+      get() {
+        return this.status === "failed";
+      },
+      enumerable: true,
+      configurable: true
+    };
+  }
+  if (Object.keys(computedProperties).length > 0) {
+    Object.defineProperties(jobResult, computedProperties);
+  }
+  return jobResult;
+}
+function sanitizePath(path2) {
+  let sanitized = path2.replace(/^\/+/, "");
+  sanitized = sanitized.replace(/\.\.(\/|\\)/g, "");
+  sanitized = sanitized.replace(/\\/g, "/");
+  return sanitized;
+}
+function getFileExtension(filename) {
+  const match = filename.match(/\.([^.]+)$/);
+  return match ? match[1].toLowerCase() : "";
+}
+function jitter(value, percent = 0.2) {
+  const randomFactor = 1 + (Math.random() * 2 - 1) * percent;
+  return Math.round(value * randomFactor);
+}
+
+// src/lib/retry.ts
+function getErrorCode(error) {
+  const errorWithResponse = error;
+  return errorWithResponse?.response?.data?.error?.code ?? errorWithResponse?.response?.data?.code ?? errorWithResponse?.code;
+}
+function getErrorDetails(error) {
+  const errorWithResponse = error;
+  return errorWithResponse?.response?.data?.error?.details ?? errorWithResponse?.response?.data?.details ?? errorWithResponse?.details;
+}
+function getBodyRetryAfter(error) {
+  const details = getErrorDetails(error);
+  if (!details) {
+    return void 0;
+  }
+  const rawRetryAfter = details.retry_after ?? details.retryAfter;
+  if (typeof rawRetryAfter === "number" && Number.isFinite(rawRetryAfter) && rawRetryAfter >= 0) {
+    return rawRetryAfter * 1e3;
+  }
+  if (typeof rawRetryAfter === "string") {
+    const parsed = Number.parseFloat(rawRetryAfter);
+    if (Number.isFinite(parsed) && parsed >= 0) {
+      return parsed * 1e3;
+    }
+  }
+  return void 0;
+}
+function shouldRetry(error, attempt, maxRetries) {
+  if (attempt >= maxRetries) {
+    return false;
+  }
+  if (isRetryableError(error)) {
+    return true;
+  }
+  return false;
+}
+function isRetryableError(error) {
+  if (error instanceof Error && (error.message.includes("ECONNRESET") || error.message.includes("ETIMEDOUT") || error.message.includes("ENOTFOUND") || error.message.includes("ECONNREFUSED"))) {
+    return true;
+  }
+  const errorWithResponse = error;
+  const statusCode = errorWithResponse?.response?.status ?? errorWithResponse?.statusCode;
+  if (statusCode && typeof statusCode === "number" && RETRYABLE_STATUS_CODES.has(statusCode)) {
+    const code = getErrorCode(error);
+    if (statusCode === 429) {
+      const retryAfter = getRetryAfter(error);
+      return retryAfter !== void 0;
+    }
+    if (statusCode === 409) {
+      return code === "ABORTED";
+    }
+    return true;
+  }
+  return false;
+}
+function calculateRetryDelay(attempt) {
+  const baseDelay = INITIAL_RETRY_DELAY * Math.pow(RETRY_DELAY_BASE, attempt);
+  const delayWithJitter = jitter(baseDelay);
+  return Math.min(delayWithJitter, MAX_RETRY_DELAY);
+}
+function getRetryAfter(error) {
+  const errorWithResponse = error;
+  if (typeof errorWithResponse?.retryAfter === "number" && Number.isFinite(errorWithResponse.retryAfter) && errorWithResponse.retryAfter >= 0) {
+    return errorWithResponse.retryAfter * 1e3;
+  }
+  const bodyRetryAfter = getBodyRetryAfter(error);
+  if (bodyRetryAfter !== void 0) {
+    return bodyRetryAfter;
+  }
+  const retryAfter = errorWithResponse?.response?.headers?.["retry-after"];
+  if (!retryAfter || typeof retryAfter !== "string") {
+    return void 0;
+  }
+  const seconds = Number.parseFloat(retryAfter);
+  if (!Number.isNaN(seconds)) {
+    return seconds * 1e3;
+  }
+  const date = new Date(retryAfter);
+  if (!isNaN(date.getTime())) {
+    return Math.max(0, date.getTime() - Date.now());
+  }
+  return void 0;
+}
+async function withRetry(fn, maxRetries, onRetry) {
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (!shouldRetry(error, attempt, maxRetries)) {
+        throw error;
+      }
+      let delay = calculateRetryDelay(attempt);
+      const retryAfter = getRetryAfter(error);
+      if (retryAfter !== void 0) {
+        delay = retryAfter;
+      }
+      if (onRetry) {
+        onRetry(attempt + 1, error);
+      }
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+  throw lastError;
+}
+
+// src/lib/http-client.ts
+var HttpClient = class {
+  axios;
+  maxRetries;
+  uploadTimeout;
+  httpAgent;
+  httpsAgent;
+  constructor(options) {
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.uploadTimeout = options.uploadTimeout ?? 6e5;
+    this.httpAgent = options.httpAgent;
+    this.httpsAgent = options.httpsAgent;
+    this.axios = import_axios.default.create({
+      baseURL: options.baseURL,
+      timeout: options.timeout ?? DEFAULT_TIMEOUT,
+      headers: {
+        "User-Agent": `knowhere-node-sdk/${VERSION}`,
+        Authorization: `Bearer ${options.apiKey}`,
+        "Content-Type": "application/json",
+        ...options.defaultHeaders
+      },
+      httpAgent: options.httpAgent,
+      httpsAgent: options.httpsAgent
+    });
+    this.setupInterceptors();
+  }
+  setupInterceptors() {
+    this.axios.interceptors.request.use(
+      (config) => {
+        if (config.data && typeof config.data === "object") {
+          config.data = keysToSnake(config.data);
+        }
+        return config;
+      },
+      (error) => {
+        return Promise.reject(this.handleError(error));
+      }
+    );
+    this.axios.interceptors.response.use(
+      (response) => {
+        if (response.data && typeof response.data === "object") {
+          let data = keysToCamel(response.data);
+          data = parseDates(data);
+          response.data = data;
+        }
+        return response;
+      },
+      (error) => {
+        return Promise.reject(this.handleError(error));
+      }
+    );
+  }
+  handleError(error) {
+    if (!error.response) {
+      if (error.code === "ECONNABORTED" || error.message.includes("timeout")) {
+        return new TimeoutError("Request timed out");
+      }
+      return new NetworkError(error.message || "Network error", error);
+    }
+    const { status, data, headers } = error.response;
+    const errorData = this.normalizeErrorData(data);
+    const errorObject = this.getErrorObject(errorData);
+    const message = this.getErrorMessage(errorObject, status);
+    const code = this.getErrorCode(errorObject);
+    const requestId = headers["x-request-id"] ?? (typeof errorObject?.request_id === "string" ? errorObject.request_id : void 0);
+    const details = errorObject?.details && typeof errorObject.details === "object" && errorObject.details.constructor === Object ? errorObject.details : void 0;
+    let retryAfter;
+    if (status === 429) {
+      const retryAfterMs = getRetryAfter(error);
+      retryAfter = retryAfterMs !== void 0 ? Math.ceil(retryAfterMs / 1e3) : void 0;
+    }
+    return createAPIError(status, message, code, requestId, details, data, retryAfter);
+  }
+  getErrorObject(errorData) {
+    if (!errorData) {
+      return void 0;
+    }
+    const nestedError = errorData.error;
+    if (nestedError && typeof nestedError === "object" && nestedError.constructor === Object) {
+      return nestedError;
+    }
+    return errorData;
+  }
+  normalizeErrorData(data) {
+    if (data && typeof data === "object" && data.constructor === Object) {
+      return data;
+    }
+    const decoded = this.decodeErrorPayload(data);
+    if (!decoded) {
+      return void 0;
+    }
+    try {
+      const parsed = JSON.parse(decoded);
+      if (parsed && typeof parsed === "object" && parsed.constructor === Object) {
+        return parsed;
+      }
+    } catch {
+    }
+    const xmlCode = decoded.match(/<Code>([^<]+)<\/Code>/i)?.[1];
+    const xmlMessage = decoded.match(/<Message>([^<]+)<\/Message>/i)?.[1];
+    if (xmlCode || xmlMessage) {
+      return {
+        code: xmlCode,
+        message: [xmlCode, xmlMessage].filter(Boolean).join(": ")
+      };
+    }
+    return {
+      message: decoded.slice(0, 300)
+    };
+  }
+  decodeErrorPayload(data) {
+    if (typeof data === "string") {
+      return data.trim();
+    }
+    if (data instanceof ArrayBuffer) {
+      return Buffer.from(data).toString("utf8").trim();
+    }
+    if (ArrayBuffer.isView(data)) {
+      return Buffer.from(data.buffer, data.byteOffset, data.byteLength).toString("utf8").trim();
+    }
+    if (Buffer.isBuffer(data)) {
+      return data.toString("utf8").trim();
+    }
+    return void 0;
+  }
+  getErrorMessage(errorData, status) {
+    if (!errorData) {
+      return `HTTP ${status} error`;
+    }
+    return typeof errorData.message === "string" ? errorData.message : typeof errorData.error === "string" ? errorData.error : `HTTP ${status} error`;
+  }
+  getErrorCode(errorData) {
+    if (!errorData) {
+      return void 0;
+    }
+    return typeof errorData.code === "string" ? errorData.code : void 0;
+  }
+  async requestExternal(request) {
+    try {
+      return await request();
+    } catch (error) {
+      if (import_axios.default.isAxiosError(error)) {
+        throw this.handleError(error);
+      }
+      throw error;
+    }
+  }
+  /**
+   * GET request
+   */
+  async get(url, config) {
+    return withRetry(
+      async () => {
+        const response = await this.axios.get(url, config);
+        return response.data;
+      },
+      this.maxRetries,
+      (attempt, error) => {
+        console.warn(`Retry attempt ${attempt} for GET ${url}:`, error);
+      }
+    );
+  }
+  /**
+   * POST request
+   */
+  async post(url, data, config) {
+    return withRetry(
+      async () => {
+        const response = await this.axios.post(url, data, config);
+        return response.data;
+      },
+      this.maxRetries,
+      (attempt, error) => {
+        console.warn(`Retry attempt ${attempt} for POST ${url}:`, error);
+      }
+    );
+  }
+  /**
+   * PUT request (typically for uploads, no retry)
+   */
+  async put(url, data, config) {
+    const response = await this.axios.put(url, data, {
+      ...config,
+      timeout: this.uploadTimeout
+    });
+    return response.data;
+  }
+  /**
+   * Download file as buffer
+   */
+  async download(url, config) {
+    return withRetry(
+      async () => {
+        return this.requestExternal(async () => {
+          const response = await import_axios.default.get(url, {
+            ...config,
+            responseType: "arraybuffer",
+            timeout: config?.timeout ?? this.uploadTimeout,
+            httpAgent: this.httpAgent,
+            httpsAgent: this.httpsAgent
+          });
+          return Buffer.from(response.data);
+        });
+      },
+      this.maxRetries,
+      (attempt, error) => {
+        console.warn(`Retry attempt ${attempt} for download ${url}:`, error);
+      }
+    );
+  }
+  /**
+   * Upload file with progress tracking
+   */
+  async upload(url, data, options) {
+    await this.requestExternal(async () => {
+      await import_axios.default.put(url, data, {
+        headers: {
+          ...options?.headers
+        },
+        timeout: this.uploadTimeout,
+        signal: options?.signal,
+        httpAgent: this.httpAgent,
+        httpsAgent: this.httpsAgent,
+        onUploadProgress: (progressEvent) => {
+          if (options?.onProgress) {
+            const loaded = progressEvent.loaded;
+            const total = progressEvent.total;
+            const percent = total ? Math.round(loaded / total * 100) : 0;
+            options.onProgress({ loaded, total, percent });
+          }
+        }
+      });
+    });
+  }
+  /**
+   * Get the underlying axios instance
+   */
+  getAxiosInstance() {
+    return this.axios;
+  }
+};
+
+// src/resources/base.ts
+var BaseResource = class {
+  httpClient;
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+};
+
+// src/lib/upload.ts
+var import_fs = require("fs");
+async function uploadFile(httpClient, uploadUrl, file, options) {
+  let data;
+  let contentLength;
+  if (typeof file === "string") {
+    const stats = await import_fs.promises.stat(file);
+    contentLength = stats.size;
+    data = (0, import_fs.createReadStream)(file);
+  } else if (file instanceof Buffer) {
+    contentLength = file.length;
+    data = file;
+  } else if (isReadStream(file)) {
+    data = file;
+    const streamWithBytes = file;
+    contentLength = streamWithBytes.bytesRead;
+  } else if (file instanceof Uint8Array) {
+    contentLength = file.length;
+    data = Buffer.from(file);
+  } else {
+    throw new ValidationError("Unsupported file type");
+  }
+  await httpClient.upload(uploadUrl, data, {
+    headers: {
+      "Content-Type": "application/octet-stream",
+      ...contentLength ? { "Content-Length": contentLength.toString() } : {},
+      ...options?.headers
+    },
+    onProgress: options?.onProgress,
+    signal: options?.signal
+  });
+}
+function isReadStream(obj) {
+  return typeof obj === "object" && obj !== null && "pipe" in obj && "read" in obj && typeof obj.pipe === "function";
+}
+
+// src/lib/polling.ts
+async function pollJobStatus(httpClient, jobId, options) {
+  const pollInterval = options?.pollInterval ?? DEFAULT_POLL_INTERVAL;
+  const pollTimeout = options?.pollTimeout ?? DEFAULT_POLL_TIMEOUT;
+  const onProgress = options?.onProgress;
+  const signal = options?.signal;
+  const startTime = Date.now();
+  let currentInterval = pollInterval;
+  while (true) {
+    if (signal?.aborted) {
+      throw new Error("Polling aborted");
+    }
+    const jobResult = await httpClient.get(`/v1/jobs/${jobId}`);
+    enrichJobResult(jobResult);
+    const elapsed = Date.now() - startTime;
+    const elapsedSeconds = Math.floor(elapsed / 1e3);
+    if (onProgress) {
+      const progress = {
+        status: jobResult.status,
+        elapsedSeconds,
+        jobResult
+      };
+      onProgress(progress);
+    }
+    if (jobResult.isTerminal) {
+      if (jobResult.isDone) {
+        return jobResult;
+      }
+      if (jobResult.isFailed && jobResult.error) {
+        throw new JobFailedError(jobResult.error.message, jobResult.error.code, jobResult);
+      }
+      throw new JobFailedError(
+        `Job ${jobId} failed with status ${jobResult.status}`,
+        "UNKNOWN_ERROR",
+        jobResult
+      );
+    }
+    if (elapsed >= pollTimeout) {
+      throw new PollingTimeoutError(`Polling timeout after ${elapsedSeconds} seconds`, elapsed);
+    }
+    if (elapsed > POLL_INTERVAL_INCREASE_THRESHOLD) {
+      currentInterval = Math.min(currentInterval * POLL_INTERVAL_MULTIPLIER, MAX_POLL_INTERVAL);
+    }
+    await sleep(currentInterval);
+  }
+}
+
+// src/lib/result-parser.ts
+var import_jszip = __toESM(require("jszip"));
+var import_fs2 = require("fs");
+var import_path = require("path");
+async function parseResult(httpClient, resultUrl, options) {
+  const zipBuffer = await httpClient.download(resultUrl);
+  if (options?.verifyChecksum !== false) {
+  }
+  const zip = await import_jszip.default.loadAsync(zipBuffer);
+  const manifestFile = zip.file("manifest.json");
+  if (!manifestFile) {
+    throw new KnowhereError("manifest.json not found in ZIP");
+  }
+  const manifestContent = await manifestFile.async("string");
+  let manifest = JSON.parse(manifestContent);
+  manifest = keysToCamel(manifest);
+  manifest = parseDates(manifest);
+  const chunksFile = zip.file("chunks.json");
+  if (!chunksFile) {
+    throw new KnowhereError("chunks.json not found in ZIP");
+  }
+  const chunksContent = await chunksFile.async("string");
+  let chunksData = JSON.parse(chunksContent);
+  chunksData = keysToCamel(chunksData);
+  const rawChunks = extractChunks(chunksData);
+  const chunks = [];
+  for (const chunkData of rawChunks) {
+    const chunk = await processChunk(zip, chunkData);
+    chunks.push(chunk);
+  }
+  let fullMarkdown;
+  const fullMdFile = zip.file("full.md");
+  if (fullMdFile) {
+    fullMarkdown = await fullMdFile.async("string");
+  }
+  let hierarchy;
+  const hierarchyFile = zip.file("hierarchy.json");
+  if (hierarchyFile) {
+    const hierarchyContent = await hierarchyFile.async("string");
+    hierarchy = JSON.parse(hierarchyContent);
+  }
+  const result = {
+    manifest,
+    chunks,
+    fullMarkdown,
+    hierarchy,
+    rawZip: zipBuffer,
+    get textChunks() {
+      return chunks.filter((c) => c.type === "text");
+    },
+    get imageChunks() {
+      return chunks.filter((c) => c.type === "image");
+    },
+    get tableChunks() {
+      return chunks.filter((c) => c.type === "table");
+    },
+    get jobId() {
+      return manifest.jobId;
+    },
+    get statistics() {
+      return manifest.statistics;
+    },
+    getChunk(chunkId) {
+      return chunks.find((c) => c.chunkId === chunkId);
+    },
+    async save(directory) {
+      await import_fs2.promises.mkdir(directory, { recursive: true });
+      await import_fs2.promises.writeFile((0, import_path.join)(directory, "manifest.json"), JSON.stringify(manifest, null, 2));
+      await import_fs2.promises.writeFile((0, import_path.join)(directory, "chunks.json"), JSON.stringify(chunks, null, 2));
+      if (fullMarkdown) {
+        await import_fs2.promises.writeFile((0, import_path.join)(directory, "full.md"), fullMarkdown);
+      }
+      if (hierarchy) {
+        await import_fs2.promises.writeFile((0, import_path.join)(directory, "hierarchy.json"), JSON.stringify(hierarchy, null, 2));
+      }
+      for (const imageChunk of this.imageChunks) {
+        await imageChunk.save(directory);
+      }
+      for (const tableChunk of this.tableChunks) {
+        await tableChunk.save(directory);
+      }
+      await import_fs2.promises.writeFile((0, import_path.join)(directory, "result.zip"), zipBuffer);
+      return directory;
+    }
+  };
+  return result;
+}
+function extractChunks(payload) {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+  if (Array.isArray(payload.chunks)) {
+    return payload.chunks;
+  }
+  return [];
+}
+function getChunkMetadata(chunkData) {
+  if (!chunkData.metadata) {
+    return {};
+  }
+  return chunkData.metadata;
+}
+function getChunkFilePath(chunkData) {
+  const metadata = getChunkMetadata(chunkData);
+  return chunkData.filePath ?? metadata.filePath ?? chunkData.path;
+}
+function normalizeTextChunk(chunkData) {
+  const metadata = getChunkMetadata(chunkData);
+  return {
+    chunkId: chunkData.chunkId ?? "",
+    type: "text",
+    content: chunkData.content ?? "",
+    path: chunkData.path ?? "",
+    length: metadata.length ?? chunkData.length ?? 0,
+    tokens: metadata.tokens ?? chunkData.tokens,
+    keywords: metadata.keywords ?? chunkData.keywords,
+    summary: metadata.summary ?? chunkData.summary,
+    relationships: metadata.relationships ?? chunkData.relationships
+  };
+}
+async function processChunk(zip, chunkData) {
+  if (chunkData.type === "text") {
+    return normalizeTextChunk(chunkData);
+  }
+  if (chunkData.type === "image") {
+    const metadata = getChunkMetadata(chunkData);
+    const filePath = getChunkFilePath(chunkData);
+    if (!filePath) {
+      throw new KnowhereError(`Image chunk missing file path: ${chunkData.chunkId ?? "unknown"}`);
+    }
+    const sanitized = sanitizePath(filePath);
+    const imageFile = zip.file(sanitized);
+    if (!imageFile) {
+      throw new KnowhereError(`Image file not found: ${filePath}`);
+    }
+    const imageBuffer = await imageFile.async("nodebuffer");
+    const enrichedChunk = {
+      chunkId: chunkData.chunkId ?? "",
+      type: "image",
+      content: chunkData.content ?? "",
+      path: chunkData.path ?? "",
+      length: metadata.length ?? chunkData.length ?? 0,
+      filePath,
+      summary: metadata.summary ?? chunkData.summary,
+      data: imageBuffer,
+      get format() {
+        return getFileExtension(this.filePath);
+      },
+      async save(directory) {
+        const outputPath = (0, import_path.join)(directory, sanitizePath(this.filePath));
+        const outputDir = (0, import_path.dirname)(outputPath);
+        await import_fs2.promises.mkdir(outputDir, { recursive: true });
+        await import_fs2.promises.writeFile(outputPath, this.data);
+        return outputPath;
+      }
+    };
+    return enrichedChunk;
+  }
+  if (chunkData.type === "table") {
+    const metadata = getChunkMetadata(chunkData);
+    const filePath = getChunkFilePath(chunkData);
+    if (!filePath) {
+      throw new KnowhereError(`Table chunk missing file path: ${chunkData.chunkId ?? "unknown"}`);
+    }
+    const sanitized = sanitizePath(filePath);
+    const htmlFile = zip.file(sanitized);
+    if (!htmlFile) {
+      throw new KnowhereError(`Table file not found: ${filePath}`);
+    }
+    const html = await htmlFile.async("string");
+    const enrichedChunk = {
+      chunkId: chunkData.chunkId ?? "",
+      type: "table",
+      content: chunkData.content ?? "",
+      path: chunkData.path ?? "",
+      length: metadata.length ?? chunkData.length ?? 0,
+      filePath,
+      tableType: metadata.tableType ?? chunkData.tableType,
+      summary: metadata.summary ?? chunkData.summary,
+      html,
+      async save(directory) {
+        const outputPath = (0, import_path.join)(directory, sanitizePath(this.filePath));
+        const outputDir = (0, import_path.dirname)(outputPath);
+        await import_fs2.promises.mkdir(outputDir, { recursive: true });
+        await import_fs2.promises.writeFile(outputPath, this.html);
+        return outputPath;
+      }
+    };
+    return enrichedChunk;
+  }
+  return normalizeTextChunk(chunkData);
+}
+
+// src/resources/jobs.ts
+var Jobs = class extends BaseResource {
+  pendingUploadJobs = /* @__PURE__ */ new Map();
+  /**
+   * Create a new parsing job
+   */
+  async create(params) {
+    const job = await this.httpClient.post("/v1/jobs", params);
+    if (job.uploadUrl) {
+      this.pendingUploadJobs.set(job.jobId, job);
+    }
+    return job;
+  }
+  /**
+   * Get job status
+   */
+  async get(jobId) {
+    const jobResult = await this.httpClient.get(`/v1/jobs/${jobId}`);
+    enrichJobResult(jobResult);
+    return jobResult;
+  }
+  /**
+   * Upload file for a job
+   */
+  async upload(jobOrId, params) {
+    const response = this.resolveUploadJob(jobOrId);
+    if (!response.uploadUrl) {
+      throw new NotFoundError(
+        "Upload URL not available for this job. Pass the Job object returned from create() or a direct upload URL string."
+      );
+    }
+    await uploadFile(this.httpClient, response.uploadUrl, params.file, {
+      headers: response.uploadHeaders,
+      onProgress: params.onProgress,
+      signal: params.signal
+    });
+    this.pendingUploadJobs.delete(response.jobId);
+  }
+  /**
+   * Wait for job completion
+   */
+  async wait(jobId, options) {
+    return pollJobStatus(this.httpClient, jobId, options);
+  }
+  /**
+   * Load parse result from completed job
+   */
+  async load(jobResultOrIdOrUrl, options) {
+    const jobResult = await this.resolveLoadJobResult(jobResultOrIdOrUrl);
+    if (!jobResult.isDone) {
+      throw new Error(`Job ${jobResult.jobId} is not done yet (status: ${jobResult.status})`);
+    }
+    if (!jobResult.resultUrl) {
+      throw new NotFoundError("Result URL not available");
+    }
+    return parseResult(this.httpClient, jobResult.resultUrl, options);
+  }
+  isHttpUrl(value) {
+    return /^https?:\/\//i.test(value);
+  }
+  resolveUploadJob(jobOrId) {
+    if (typeof jobOrId !== "string") {
+      if (jobOrId.uploadUrl) {
+        this.pendingUploadJobs.set(jobOrId.jobId, jobOrId);
+      }
+      return jobOrId;
+    }
+    if (this.isHttpUrl(jobOrId)) {
+      return {
+        jobId: "direct-upload-url",
+        status: "waiting-file",
+        sourceType: "file",
+        createdAt: /* @__PURE__ */ new Date(0),
+        uploadUrl: jobOrId
+      };
+    }
+    const cachedJob = this.pendingUploadJobs.get(jobOrId);
+    if (cachedJob) {
+      return cachedJob;
+    }
+    throw new InvalidStateError(
+      `Upload URL not available for job ${jobOrId}. Pass the Job object returned from create() or a direct upload URL string.`
+    );
+  }
+  async resolveLoadJobResult(jobResultOrIdOrUrl) {
+    if (typeof jobResultOrIdOrUrl !== "string") {
+      enrichJobResult(jobResultOrIdOrUrl);
+      return jobResultOrIdOrUrl;
+    }
+    if (this.isHttpUrl(jobResultOrIdOrUrl)) {
+      return {
+        jobId: "direct-result-url",
+        status: "done",
+        sourceType: "file",
+        createdAt: /* @__PURE__ */ new Date(0),
+        resultUrl: jobResultOrIdOrUrl,
+        resultUrlExpiresAt: /* @__PURE__ */ new Date(0),
+        isTerminal: true,
+        isDone: true,
+        isFailed: false
+      };
+    }
+    return this.get(jobResultOrIdOrUrl);
+  }
+};
+
+// src/client.ts
+function inferFileName(file, explicitFileName) {
+  if (explicitFileName) {
+    return explicitFileName;
+  }
+  if (typeof file === "string") {
+    return import_path2.default.basename(file);
+  }
+  if (isReadStream2(file) && typeof file.path === "string") {
+    return import_path2.default.basename(file.path);
+  }
+  return void 0;
+}
+function isReadStream2(file) {
+  return typeof file === "object" && file !== null && "pipe" in file && typeof file.pipe === "function";
+}
+var Knowhere = class {
+  /** Jobs resource for low-level API */
+  jobs;
+  httpClient;
+  /**
+   * Create a new Knowhere client
+   */
+  constructor(options = {}) {
+    const apiKey = options.apiKey ?? process.env[ENV.API_KEY];
+    if (!apiKey) {
+      throw new ValidationError(
+        `API key is required. Provide it via options.apiKey or ${ENV.API_KEY} environment variable.`
+      );
+    }
+    const baseURL = options.baseURL ?? process.env[ENV.BASE_URL] ?? DEFAULT_BASE_URL;
+    this.httpClient = new HttpClient({
+      baseURL,
+      apiKey,
+      timeout: options.timeout,
+      uploadTimeout: options.uploadTimeout,
+      maxRetries: options.maxRetries,
+      defaultHeaders: options.defaultHeaders,
+      httpAgent: options.httpAgent,
+      httpsAgent: options.httpsAgent
+    });
+    this.jobs = new Jobs(this.httpClient);
+  }
+  /**
+   * High-level API: Parse a document and return structured results
+   *
+   * @example
+   * ```typescript
+   * // Parse from URL
+   * const result = await client.parse({ url: 'https://example.com/doc.pdf' });
+   *
+   * // Parse from file
+   * const result = await client.parse({ file: './document.pdf' });
+   *
+   * // Parse with options
+   * const result = await client.parse({
+   *   url: 'https://example.com/doc.pdf',
+   *   model: 'advanced',
+   *   ocr: true,
+   *   onUploadProgress: (p) => console.log(`${p.percent}%`),
+   * });
+   * ```
+   */
+  async parse(params) {
+    if (!params.url && !params.file) {
+      throw new ValidationError("Either url or file must be provided");
+    }
+    if (params.url && params.file) {
+      throw new ValidationError("Only one of url or file can be provided");
+    }
+    const sourceType = params.url ? "url" : "file";
+    const resolvedFileName = inferFileName(params.file, params.fileName);
+    if (params.file && !resolvedFileName) {
+      throw new ValidationError(
+        "fileName is required when file is a Buffer, Uint8Array, or stream without a path."
+      );
+    }
+    const parsingParams = {
+      model: params.model,
+      ocrEnabled: params.ocr,
+      docType: params.docType,
+      smartTitleParse: params.smartTitleParse,
+      summaryImage: params.summaryImage,
+      summaryTable: params.summaryTable,
+      summaryTxt: params.summaryText,
+      addFragDesc: params.addFragDesc,
+      kbDir: params.kbDir
+    };
+    Object.keys(parsingParams).forEach((key) => {
+      if (parsingParams[key] === void 0) {
+        delete parsingParams[key];
+      }
+    });
+    const webhook = params.webhook;
+    const job = await this.jobs.create({
+      sourceType,
+      sourceUrl: params.url,
+      fileName: resolvedFileName,
+      dataId: params.dataId,
+      parsingParams: Object.keys(parsingParams).length > 0 ? parsingParams : void 0,
+      webhook
+    });
+    if (params.file) {
+      await this.jobs.upload(job, {
+        file: params.file,
+        onProgress: params.onUploadProgress,
+        signal: params.signal
+      });
+    }
+    const jobResult = await this.jobs.wait(job.jobId, {
+      pollInterval: params.pollInterval,
+      pollTimeout: params.pollTimeout,
+      onProgress: params.onPollProgress,
+      signal: params.signal
+    });
+    const result = await this.jobs.load(jobResult, {
+      verifyChecksum: params.verifyChecksum
+    });
+    return result;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  APIError,
+  AuthenticationError,
+  BadRequestError,
+  ChecksumError,
+  ConflictError,
+  GatewayTimeoutError,
+  InternalServerError,
+  InvalidStateError,
+  JobFailedError,
+  Jobs,
+  Knowhere,
+  KnowhereError,
+  NetworkError,
+  NotFoundError,
+  PaymentRequiredError,
+  PermissionDeniedError,
+  PollingTimeoutError,
+  RateLimitError,
+  ServiceUnavailableError,
+  TimeoutError,
+  VERSION,
+  ValidationError
+});