@pulseindex/sdk 2.0.0

package/dist/index.js

@@ -0,0 +1,1195 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var grpc2 = require('@grpc/grpc-js');
+var fs = require('fs');
+var path = require('path');
+var url = require('url');
+var protoLoader = require('@grpc/proto-loader');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var grpc2__namespace = /*#__PURE__*/_interopNamespace(grpc2);
+var protoLoader__namespace = /*#__PURE__*/_interopNamespace(protoLoader);
+
+// node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/geo/GeoHash.ts
+var GeoHash = class {
+  static TAG_PREFIX = "geo:";
+  static MIN_PRECISION = 1;
+  static MAX_PRECISION = 12;
+  static INDEX_PRECISIONS = [5, 6];
+  static BASE32 = "0123456789bcdefghjkmnpqrstuvwxyz";
+  static EARTH_RADIUS_KM = 6371;
+  static MAX_COVERING_CELLS = 64;
+  static NEIGHBORS = {
+    n: ["p0r21436x8zb9dcf5h7kjnmqesgutwvy", "bc01fg45238967deuvhjyznpkmstqrwx"],
+    s: ["14365h7k9dcfesgujnmqp0r2twvyx8zb", "238967debc01fg45kmstqrwxuvhjyznp"],
+    e: ["bc01fg45238967deuvhjyznpkmstqrwx", "p0r21436x8zb9dcf5h7kjnmqesgutwvy"],
+    w: ["238967debc01fg45kmstqrwxuvhjyznp", "14365h7k9dcfesgujnmqp0r2twvyx8zb"]
+  };
+  static BORDERS = {
+    n: ["prxz", "bcfguvyz"],
+    s: ["028b", "0145hjnp"],
+    e: ["bcfguvyz", "prxz"],
+    w: ["0145hjnp", "028b"]
+  };
+  static encode(lat, lon, precision = 6) {
+    this.assertLatitude(lat);
+    this.assertLongitude(lon);
+    this.assertPrecision(precision);
+    let latMin = -90;
+    let latMax = 90;
+    let lonMin = -180;
+    let lonMax = 180;
+    let hash = "";
+    let bit = 0;
+    let ch = 0;
+    let even = true;
+    while (hash.length < precision) {
+      if (even) {
+        const mid = (lonMin + lonMax) / 2;
+        if (lon >= mid) {
+          ch |= 1 << 4 - bit;
+          lonMin = mid;
+        } else {
+          lonMax = mid;
+        }
+      } else {
+        const mid = (latMin + latMax) / 2;
+        if (lat >= mid) {
+          ch |= 1 << 4 - bit;
+          latMin = mid;
+        } else {
+          latMax = mid;
+        }
+      }
+      even = !even;
+      if (bit < 4) {
+        bit += 1;
+      } else {
+        hash += this.BASE32[ch];
+        bit = 0;
+        ch = 0;
+      }
+    }
+    return hash;
+  }
+  static decode(hash) {
+    const bounds = this.decodeBounds(hash);
+    return {
+      lat: (bounds.latMin + bounds.latMax) / 2,
+      lon: (bounds.lonMin + bounds.lonMax) / 2
+    };
+  }
+  static decodeBounds(hash) {
+    const normalized = this.normalizeHash(hash);
+    let latMin = -90;
+    let latMax = 90;
+    let lonMin = -180;
+    let lonMax = 180;
+    let even = true;
+    for (const character of normalized) {
+      const cd = this.BASE32.indexOf(character);
+      if (cd < 0) {
+        throw new Error(`Invalid GeoHash character "${character}".`);
+      }
+      for (let mask = 16; mask > 0; mask >>= 1) {
+        if (even) {
+          const mid = (lonMin + lonMax) / 2;
+          if ((cd & mask) !== 0) {
+            lonMin = mid;
+          } else {
+            lonMax = mid;
+          }
+        } else {
+          const mid = (latMin + latMax) / 2;
+          if ((cd & mask) !== 0) {
+            latMin = mid;
+          } else {
+            latMax = mid;
+          }
+        }
+        even = !even;
+      }
+    }
+    return { latMin, latMax, lonMin, lonMax };
+  }
+  static neighbor(hash, direction) {
+    const normalizedDirection = direction.toLowerCase();
+    if (!this.isCardinal(normalizedDirection)) {
+      throw new Error("Direction must be one of: n, s, e, w.");
+    }
+    return this.adjacent(this.normalizeHash(hash), normalizedDirection);
+  }
+  static neighbors(hash) {
+    const normalized = this.normalizeHash(hash);
+    const north = this.adjacent(normalized, "n");
+    const south = this.adjacent(normalized, "s");
+    const east = this.adjacent(normalized, "e");
+    const west = this.adjacent(normalized, "w");
+    return [
+      north,
+      this.adjacent(north, "e"),
+      east,
+      this.adjacent(south, "e"),
+      south,
+      this.adjacent(south, "w"),
+      west,
+      this.adjacent(north, "w")
+    ];
+  }
+  static neighborhood3x3(hash) {
+    const center = this.normalizeHash(hash);
+    return [center, ...this.neighbors(center)];
+  }
+  static neighborhoodTags(lat, lon, precision = 6) {
+    return this.neighborhood3x3(this.encode(lat, lon, precision)).map((cell) => this.tag(cell));
+  }
+  static optimalPrecisionForRadius(radiusKm) {
+    if (radiusKm < 0) {
+      throw new Error("Radius must be non-negative.");
+    }
+    if (radiusKm <= 1.5) {
+      return 6;
+    }
+    if (radiusKm <= 8) {
+      return 5;
+    }
+    return 4;
+  }
+  static precisionForRadius(radiusKm) {
+    return this.optimalPrecisionForRadius(radiusKm);
+  }
+  static getCoveringHashes(lat, lon, radiusKm, precision) {
+    if (radiusKm < 0) {
+      throw new Error("Radius must be non-negative.");
+    }
+    const resolvedPrecision = precision ?? this.optimalPrecisionForRadius(radiusKm);
+    this.assertPrecision(resolvedPrecision);
+    const center = this.encode(lat, lon, resolvedPrecision);
+    const covering = [];
+    const visited = /* @__PURE__ */ new Set();
+    const queue = [center];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (current === void 0 || visited.has(current)) {
+        continue;
+      }
+      visited.add(current);
+      if (!this.cellIntersectsCircle(current, lat, lon, radiusKm)) {
+        continue;
+      }
+      covering.push(current);
+      if (covering.length >= this.MAX_COVERING_CELLS) {
+        break;
+      }
+      for (const neighbor of this.neighbors(current)) {
+        if (!visited.has(neighbor)) {
+          queue.push(neighbor);
+        }
+      }
+    }
+    return covering;
+  }
+  static tag(geohash) {
+    const hash = this.normalizeHash(geohash);
+    return `${this.TAG_PREFIX}${hash.length}:${hash}`;
+  }
+  static encodeTag(lat, lon, precision = 6) {
+    return this.tag(this.encode(lat, lon, precision));
+  }
+  static encodeMultiTags(lat, lon) {
+    return this.INDEX_PRECISIONS.map((precision) => this.encodeTag(lat, lon, precision));
+  }
+  static haversineKm(lat1, lon1, lat2, lon2) {
+    const dLat = this.toRadians(lat2 - lat1);
+    const dLon = this.toRadians(lon2 - lon1);
+    const a = Math.sin(dLat / 2) ** 2 + Math.cos(this.toRadians(lat1)) * Math.cos(this.toRadians(lat2)) * Math.sin(dLon / 2) ** 2;
+    return 2 * this.EARTH_RADIUS_KM * Math.asin(Math.min(1, Math.sqrt(a)));
+  }
+  static cellIntersectsCircle(hash, lat, lon, radiusKm) {
+    const bounds = this.decodeBounds(hash);
+    const closestLat = Math.min(Math.max(lat, bounds.latMin), bounds.latMax);
+    const closestLon = Math.min(Math.max(lon, bounds.lonMin), bounds.lonMax);
+    return this.haversineKm(lat, lon, closestLat, closestLon) <= radiusKm;
+  }
+  static adjacent(hash, direction) {
+    if (hash.length === 0) {
+      throw new Error("GeoHash must not be empty.");
+    }
+    const lastChar = hash[hash.length - 1] ?? "";
+    const type = hash.length % 2;
+    let parent = hash.slice(0, -1);
+    const borders = this.BORDERS[direction][type] ?? "";
+    if (parent.length > 0 && borders.includes(lastChar)) {
+      parent = this.adjacent(parent, direction);
+    }
+    const neighborCharset = this.NEIGHBORS[direction][type] ?? "";
+    const index = neighborCharset.indexOf(lastChar);
+    if (index < 0) {
+      throw new Error(`Invalid GeoHash character "${lastChar}".`);
+    }
+    return parent + (this.BASE32[index] ?? "");
+  }
+  static normalizeHash(hash) {
+    let normalized = hash.trim().toLowerCase();
+    if (normalized.startsWith(this.TAG_PREFIX)) {
+      normalized = normalized.slice(this.TAG_PREFIX.length);
+    }
+    const tagged = normalized.match(/^([1-9]|1[0-2]):([0-9bcdefghjkmnpqrstuvwxyz]+)$/);
+    if (tagged) {
+      normalized = tagged[2] ?? "";
+    }
+    if (normalized.length === 0) {
+      throw new Error("GeoHash must not be empty.");
+    }
+    for (const character of normalized) {
+      if (!this.BASE32.includes(character)) {
+        throw new Error(`Invalid GeoHash "${normalized}".`);
+      }
+    }
+    return normalized;
+  }
+  static assertLatitude(lat) {
+    if (!Number.isFinite(lat) || lat < -90 || lat > 90) {
+      throw new Error("Latitude must be between -90 and 90.");
+    }
+  }
+  static assertLongitude(lon) {
+    if (!Number.isFinite(lon) || lon < -180 || lon > 180) {
+      throw new Error("Longitude must be between -180 and 180.");
+    }
+  }
+  static assertPrecision(precision) {
+    if (!Number.isInteger(precision) || precision < this.MIN_PRECISION || precision > this.MAX_PRECISION) {
+      throw new Error(
+        `GeoHash precision must be between ${this.MIN_PRECISION} and ${this.MAX_PRECISION}.`
+      );
+    }
+  }
+  static isCardinal(direction) {
+    return direction === "n" || direction === "s" || direction === "e" || direction === "w";
+  }
+  static toRadians(degrees) {
+    return degrees * Math.PI / 180;
+  }
+};
+var PulseIndexError = class _PulseIndexError extends Error {
+  code;
+  grpcStatusCode;
+  grpcDetails;
+  constructor(message, options = {}) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = "PulseIndexError";
+    this.code = options.code ?? "PULSEINDEX_ERROR";
+    this.grpcStatusCode = options.grpcStatusCode;
+    this.grpcDetails = options.grpcDetails;
+  }
+  static fromGrpc(error) {
+    const serviceError = error;
+    const grpcStatusCode = typeof serviceError.code === "number" ? serviceError.code : grpc2.status.UNKNOWN;
+    const grpcDetails = typeof serviceError.details === "string" && serviceError.details.length > 0 ? serviceError.details : error.message;
+    const message = grpcDetails.length > 0 ? grpcDetails : `gRPC call failed with status ${grpcStatusName(grpcStatusCode)} (${grpcStatusCode})`;
+    const base = {
+      grpcStatusCode,
+      grpcDetails,
+      cause: error
+    };
+    switch (grpcStatusCode) {
+      case grpc2.status.UNAUTHENTICATED:
+      case grpc2.status.PERMISSION_DENIED:
+        return new PulseIndexAuthError(message, {
+          ...base,
+          code: grpcStatusCode === grpc2.status.PERMISSION_DENIED ? "PERMISSION_DENIED" : "UNAUTHENTICATED"
+        });
+      case grpc2.status.UNAVAILABLE:
+      case grpc2.status.DEADLINE_EXCEEDED:
+      case grpc2.status.CANCELLED:
+      case grpc2.status.ABORTED:
+        return new PulseIndexConnectionError(message, {
+          ...base,
+          code: grpcStatusName(grpcStatusCode)
+        });
+      case grpc2.status.INVALID_ARGUMENT:
+      case grpc2.status.FAILED_PRECONDITION:
+      case grpc2.status.OUT_OF_RANGE:
+      case grpc2.status.NOT_FOUND:
+      case grpc2.status.ALREADY_EXISTS:
+      case grpc2.status.RESOURCE_EXHAUSTED:
+        return new PulseIndexQueryError(message, {
+          ...base,
+          code: grpcStatusName(grpcStatusCode)
+        });
+      default:
+        return new _PulseIndexError(message, {
+          ...base,
+          code: grpcStatusName(grpcStatusCode)
+        });
+    }
+  }
+};
+var PulseIndexConnectionError = class extends PulseIndexError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: options.code ?? "CONNECTION_ERROR" });
+    this.name = "PulseIndexConnectionError";
+  }
+};
+var PulseIndexAuthError = class extends PulseIndexError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: options.code ?? "AUTH_ERROR" });
+    this.name = "PulseIndexAuthError";
+  }
+};
+var PulseIndexQueryError = class extends PulseIndexError {
+  constructor(message, options = {}) {
+    super(message, { ...options, code: options.code ?? "QUERY_ERROR" });
+    this.name = "PulseIndexQueryError";
+  }
+};
+function grpcStatusName(code) {
+  const names = Object.entries(grpc2.status).find(([, value]) => value === code);
+  return names?.[0] ?? `STATUS_${code}`;
+}
+
+// src/types/index.ts
+var FilterOperation = {
+  MUST: 0,
+  SHOULD: 1,
+  MUST_NOT: 2
+};
+var UINT32_MAX = 4294967295;
+var DEFAULT_ENDPOINT = "localhost:50051";
+var DEFAULT_TIMEOUT_MS = 5e3;
+var DEFAULT_POOL_SIZE = 1;
+
+// src/builder/QueryBuilder.ts
+function emptyState() {
+  return {
+    tenantId: "",
+    locationPrefix: "0",
+    limit: 0,
+    offset: 0,
+    filters: [],
+    ranges: []
+  };
+}
+function asAttributeList(value) {
+  const items = Array.isArray(value) ? value : [value];
+  const normalized = items.map((item) => item.trim()).filter((item) => item.length > 0);
+  if (normalized.length === 0) {
+    throw new PulseIndexQueryError("Attribute filter must not be empty.");
+  }
+  return normalized;
+}
+function resolveLongitude(options) {
+  const value = options.lng ?? options.lon;
+  if (value === void 0) {
+    throw new PulseIndexQueryError("withinRadius requires lng or lon.");
+  }
+  return value;
+}
+var QueryBuilder = class _QueryBuilder {
+  executor;
+  state;
+  constructor(executor = null) {
+    this.executor = executor;
+    this.state = emptyState();
+  }
+  tenant(tenantId) {
+    return this.fork((state) => {
+      state.tenantId = tenantId;
+    });
+  }
+  location(locationPrefix) {
+    return this.fork((state) => {
+      state.locationPrefix = String(locationPrefix);
+    });
+  }
+  must(attribute) {
+    return this.addFilters(FilterOperation.MUST, attribute);
+  }
+  should(attribute) {
+    return this.addFilters(FilterOperation.SHOULD, attribute);
+  }
+  mustNot(attribute) {
+    return this.addFilters(FilterOperation.MUST_NOT, attribute);
+  }
+  whereGeoHash(geohash) {
+    return this.must(GeoHash.tag(geohash));
+  }
+  inGeoHash(geohash) {
+    return this.whereGeoHash(geohash);
+  }
+  withinRadius(latOrOptions, lon, radiusKm, precision) {
+    let lat;
+    let longitude;
+    let radius;
+    let resolvedPrecision;
+    if (typeof latOrOptions === "object") {
+      lat = latOrOptions.lat;
+      longitude = resolveLongitude(latOrOptions);
+      radius = latOrOptions.radiusKm;
+      resolvedPrecision = latOrOptions.precision;
+    } else {
+      if (lon === void 0 || radiusKm === void 0) {
+        throw new PulseIndexQueryError("withinRadius(lat, lon, radiusKm) requires all three arguments.");
+      }
+      lat = latOrOptions;
+      longitude = lon;
+      radius = radiusKm;
+      resolvedPrecision = precision;
+    }
+    const covering = GeoHash.getCoveringHashes(lat, longitude, radius, resolvedPrecision);
+    return this.fork((state) => {
+      for (const hash of covering) {
+        state.filters.push({
+          op: FilterOperation.SHOULD,
+          attribute: GeoHash.tag(hash)
+        });
+      }
+    });
+  }
+  range(field, min, max) {
+    if (!field.trim()) {
+      throw new PulseIndexQueryError("Range field must not be empty.");
+    }
+    if (!Number.isFinite(min) || !Number.isFinite(max)) {
+      throw new PulseIndexQueryError("Range bounds must be finite numbers.");
+    }
+    if (min > max) {
+      throw new PulseIndexQueryError(`Range min (${min}) must be <= max (${max}).`);
+    }
+    return this.fork((state) => {
+      state.ranges.push({
+        field,
+        minVal: Math.floor(min),
+        maxVal: Math.floor(max)
+      });
+    });
+  }
+  limit(limit) {
+    return this.fork((state) => {
+      state.limit = Math.max(0, Math.floor(limit));
+    });
+  }
+  offset(offset) {
+    return this.fork((state) => {
+      state.offset = Math.max(0, Math.floor(offset));
+    });
+  }
+  toRequest(defaultTenantId = "") {
+    return {
+      tenantId: this.state.tenantId || defaultTenantId,
+      locationPrefix: this.state.locationPrefix,
+      limit: this.state.limit,
+      offset: this.state.offset,
+      filters: this.state.filters.map((filter) => ({ ...filter })),
+      ranges: this.state.ranges.map((range) => ({ ...range }))
+    };
+  }
+  toArray(defaultTenantId = "") {
+    return this.toRequest(defaultTenantId);
+  }
+  execute() {
+    if (!this.executor) {
+      throw new PulseIndexQueryError(
+        "QueryBuilder has no client; pass the builder to client.search() or create it via client.query()."
+      );
+    }
+    return this.executor.search(this);
+  }
+  static fromOptions(options, executor = null) {
+    let query = new _QueryBuilder(executor);
+    if (options.tenantId !== void 0) {
+      query = query.tenant(options.tenantId);
+    }
+    if (options.locationPrefix !== void 0) {
+      query = query.location(options.locationPrefix);
+    }
+    if (options.must !== void 0) {
+      query = query.must(options.must);
+    }
+    if (options.should !== void 0) {
+      query = query.should(options.should);
+    }
+    if (options.mustNot !== void 0) {
+      query = query.mustNot(options.mustNot);
+    }
+    if (options.ranges) {
+      for (const range of options.ranges) {
+        query = query.range(range.field, range.min, range.max);
+      }
+    }
+    if (options.withinRadius) {
+      query = query.withinRadius(options.withinRadius);
+    }
+    if (options.geoHash) {
+      query = query.whereGeoHash(options.geoHash);
+    }
+    if (options.limit !== void 0) {
+      query = query.limit(options.limit);
+    }
+    if (options.offset !== void 0) {
+      query = query.offset(options.offset);
+    }
+    return query;
+  }
+  addFilters(op, attribute) {
+    const attributes = asAttributeList(attribute);
+    return this.fork((state) => {
+      for (const value of attributes) {
+        state.filters.push({ op, attribute: value });
+      }
+    });
+  }
+  fork(mutate) {
+    const next = new _QueryBuilder(this.executor);
+    next.state = {
+      tenantId: this.state.tenantId,
+      locationPrefix: this.state.locationPrefix,
+      limit: this.state.limit,
+      offset: this.state.offset,
+      filters: this.state.filters.map((filter) => ({ ...filter })),
+      ranges: this.state.ranges.map((range) => ({ ...range }))
+    };
+    mutate(next.state);
+    return next;
+  }
+};
+var PROTO_LOADER_OPTIONS = {
+  keepCase: false,
+  longs: String,
+  enums: Number,
+  defaults: true,
+  oneofs: true
+};
+var cache = /* @__PURE__ */ new Map();
+function resolveProtoPath(fileName, explicit) {
+  if (explicit) {
+    if (!fs.existsSync(explicit)) {
+      throw new PulseIndexError(`${fileName} not found at ${explicit}`, {
+        code: "PROTO_NOT_FOUND"
+      });
+    }
+    return explicit;
+  }
+  const here = typeof __dirname === "string" && __dirname.length > 0 ? __dirname : path.dirname(url.fileURLToPath(importMetaUrl));
+  const candidates = [
+    path.join(here, "..", "..", "proto", fileName),
+    path.join(here, "..", "proto", fileName),
+    path.join(here, "proto", fileName),
+    path.join(process.cwd(), "proto", fileName)
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  throw new PulseIndexError(
+    `${fileName} not found. Looked in: ${candidates.join(", ")}`,
+    { code: "PROTO_NOT_FOUND" }
+  );
+}
+function resolveEngineProtoPath(explicit) {
+  return resolveProtoPath("engine.proto", explicit);
+}
+function resolveHealthProtoPath(explicit) {
+  return resolveProtoPath("health.proto", explicit);
+}
+function loadEngineProto(protoPath) {
+  const resolved = resolveEngineProtoPath(protoPath);
+  const cached = cache.get(resolved);
+  if (cached) {
+    return cached;
+  }
+  const definition = protoLoader__namespace.loadSync(resolved, PROTO_LOADER_OPTIONS);
+  const grpcObject = grpc2__namespace.loadPackageDefinition(definition);
+  const serviceCtor = grpcObject.pulseindex?.engine?.v1?.SearchEngineService;
+  if (!serviceCtor) {
+    throw new PulseIndexError(
+      "Failed to load pulseindex.engine.v1.SearchEngineService from engine.proto",
+      { code: "PROTO_LOAD_FAILED" }
+    );
+  }
+  const loaded = {
+    protoPath: resolved,
+    SearchEngineService: serviceCtor,
+    service: serviceCtor.service
+  };
+  cache.set(resolved, loaded);
+  return loaded;
+}
+var SERVING_STATUS = {
+  UNKNOWN: 0,
+  SERVING: 1,
+  NOT_SERVING: 2,
+  SERVICE_UNKNOWN: 3
+};
+var healthCache = /* @__PURE__ */ new Map();
+function loadHealthProto(protoPath) {
+  const resolved = resolveHealthProtoPath(protoPath);
+  const cached = healthCache.get(resolved);
+  if (cached) {
+    return cached;
+  }
+  const definition = protoLoader__namespace.loadSync(resolved, PROTO_LOADER_OPTIONS);
+  const grpcObject = grpc2__namespace.loadPackageDefinition(definition);
+  const ctor = grpcObject.grpc?.health?.v1?.Health;
+  if (!ctor) {
+    throw new PulseIndexError(
+      "Failed to load grpc.health.v1.Health from health.proto",
+      { code: "PROTO_LOAD_FAILED" }
+    );
+  }
+  healthCache.set(resolved, ctor);
+  return ctor;
+}
+
+// src/client/ConnectionManager.ts
+var DEFAULT_CHANNEL_OPTIONS = {
+  "grpc.keepalive_time_ms": 3e4,
+  "grpc.keepalive_timeout_ms": 5e3,
+  "grpc.keepalive_permit_without_calls": 1,
+  "grpc.http2.min_time_between_pings_ms": 1e4,
+  "grpc.max_receive_message_length": 16 * 1024 * 1024,
+  "grpc.max_send_message_length": 16 * 1024 * 1024
+};
+function resolveEndpoint(config) {
+  return config.endpoint ?? config.host ?? process.env.PULSEINDEX_ENDPOINT ?? process.env.PULSEINDEX_HOST ?? DEFAULT_ENDPOINT;
+}
+function resolveApiKey(config) {
+  const key = config.apiKey ?? process.env.PULSEINDEX_API_KEY ?? void 0;
+  if (typeof key !== "string" || key.trim().length === 0) {
+    return void 0;
+  }
+  return key.trim();
+}
+function resolveAuthorization(config) {
+  const token = config.authorization ?? process.env.PULSEINDEX_AUTHORIZATION ?? void 0;
+  if (typeof token !== "string" || token.trim().length === 0) {
+    return void 0;
+  }
+  return token.trim();
+}
+function resolveTenantId(config) {
+  return config.tenantId ?? process.env.PULSEINDEX_TENANT_ID ?? "";
+}
+function sslEnabled(config) {
+  if (config.ssl !== void 0) {
+    return parseBoolean(config.ssl);
+  }
+  const env = process.env.PULSEINDEX_SSL;
+  if (env === void 0 || env === "") {
+    return false;
+  }
+  return parseBoolean(env);
+}
+function parseBoolean(value) {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return value === 1;
+  }
+  const normalized = value.trim().toLowerCase();
+  return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+var ConnectionManager = class {
+  endpoint;
+  tenantId;
+  timeoutMs;
+  ssl;
+  apiKey;
+  authorization;
+  clients = [];
+  cursor = 0;
+  closed = false;
+  // Kept so the health stub can be built on demand with exactly the same
+  // address, credentials and options. grpc-js pools subchannels by that
+  // triple, so it rides the connection the engine pool already opened rather
+  // than dialling a second one.
+  credentials;
+  channelOptions;
+  healthProtoPath;
+  healthStub;
+  constructor(config = {}) {
+    this.endpoint = resolveEndpoint(config);
+    this.tenantId = resolveTenantId(config);
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.ssl = sslEnabled(config);
+    this.apiKey = resolveApiKey(config);
+    this.authorization = resolveAuthorization(config);
+    const poolSize = Math.max(1, Math.floor(config.poolSize ?? DEFAULT_POOL_SIZE));
+    const credentials2 = this.createCredentials(config);
+    const { SearchEngineService } = loadEngineProto(config.protoPath);
+    const channelOptions = {
+      ...DEFAULT_CHANNEL_OPTIONS,
+      ...config.channelOptions ?? {}
+    };
+    for (let i = 0; i < poolSize; i += 1) {
+      this.clients.push(new SearchEngineService(this.endpoint, credentials2, channelOptions));
+    }
+    this.credentials = credentials2;
+    this.channelOptions = channelOptions;
+    this.healthProtoPath = config.healthProtoPath;
+  }
+  /**
+   * `grpc.health.v1.Health` stub, created on first use.
+   *
+   * A separate service from the query API, and unauthenticated: the health
+   * protocol needs no scope, so it works with any key or none.
+   */
+  getHealthStub() {
+    this.assertOpen();
+    if (!this.healthStub) {
+      const Health = loadHealthProto(this.healthProtoPath);
+      this.healthStub = new Health(this.endpoint, this.credentials, this.channelOptions);
+    }
+    return this.healthStub;
+  }
+  getStub() {
+    this.assertOpen();
+    const stub = this.clients[this.cursor % this.clients.length];
+    this.cursor += 1;
+    if (!stub) {
+      throw new PulseIndexConnectionError("PulseIndex gRPC channel pool is empty.");
+    }
+    return stub;
+  }
+  createMetadata() {
+    const metadata = new grpc2__namespace.Metadata();
+    if (this.apiKey) {
+      metadata.set("x-api-key", this.apiKey);
+    }
+    const bearer = this.authorization ? this.authorization.toLowerCase().startsWith("bearer ") ? this.authorization : `Bearer ${this.authorization}` : this.apiKey ? `Bearer ${this.apiKey}` : void 0;
+    if (bearer) {
+      metadata.set("authorization", bearer);
+    }
+    return metadata;
+  }
+  createCallOptions() {
+    return {
+      deadline: Date.now() + this.timeoutMs
+    };
+  }
+  async waitForReady(timeoutMs = this.timeoutMs) {
+    this.assertOpen();
+    const deadline = new Date(Date.now() + timeoutMs);
+    await Promise.all(
+      this.clients.map(
+        (client) => new Promise((resolve, reject) => {
+          client.waitForReady(deadline, (error) => {
+            if (error) {
+              reject(
+                new PulseIndexConnectionError(
+                  `Unable to connect to PulseIndex at ${this.endpoint}: ${error.message}`,
+                  { cause: error, code: "UNAVAILABLE" }
+                )
+              );
+              return;
+            }
+            resolve();
+          });
+        })
+      )
+    );
+  }
+  close() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    for (const client of this.clients) {
+      client.close();
+    }
+    this.clients.length = 0;
+    this.healthStub?.close();
+    this.healthStub = void 0;
+  }
+  assertOpen() {
+    if (this.closed) {
+      throw new PulseIndexConnectionError("PulseIndex client has been closed.");
+    }
+  }
+  createCredentials(config) {
+    if (!this.ssl) {
+      return grpc2__namespace.credentials.createInsecure();
+    }
+    return grpc2__namespace.credentials.createSsl(
+      config.rootCerts ?? null,
+      config.privateKey ?? null,
+      config.certChain ?? null
+    );
+  }
+};
+
+// src/client/encodeEntity.ts
+var SKIP_ATTRIBUTE_KEYS = /* @__PURE__ */ new Set([
+  "id",
+  "entityId",
+  "entity_id",
+  "attributes",
+  "price",
+  "locationPrefix",
+  "location_prefix",
+  "tenantId",
+  "tenant_id",
+  "latitude",
+  "longitude",
+  "lat",
+  "lng",
+  "lon",
+  "categories",
+  "tags"
+]);
+function toUint64String(value, field = "entityId") {
+  if (typeof value === "bigint") {
+    if (value < 0n) {
+      throw new PulseIndexQueryError(`${field} must be a non-negative integer.`);
+    }
+    return value.toString(10);
+  }
+  if (typeof value === "number") {
+    if (!Number.isInteger(value) || value < 0 || !Number.isSafeInteger(value)) {
+      throw new PulseIndexQueryError(
+        `${field} must be a non-negative safe integer, bigint, or digit string.`
+      );
+    }
+    return String(value);
+  }
+  const trimmed = value.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    throw new PulseIndexQueryError(`${field} must be a non-negative integer string.`);
+  }
+  return trimmed.replace(/^0+(?=\d)/, "");
+}
+function toUint32(value, field) {
+  if (value === void 0 || value === null || value === "") {
+    return 0;
+  }
+  const numeric = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(numeric) || numeric < 0 || numeric > UINT32_MAX) {
+    throw new PulseIndexQueryError(`${field} must be an integer between 0 and ${UINT32_MAX}.`);
+  }
+  return Math.floor(numeric);
+}
+function asRecord(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  return {};
+}
+function pushScalarTag(target, value) {
+  if (typeof value === "boolean") {
+    return;
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "bigint") {
+    const text = String(value).trim();
+    if (text.length > 0) {
+      target.push(text);
+    }
+  }
+}
+function flattenAttributes(attributes) {
+  const categories = [];
+  for (const listKey of ["categories", "tags"]) {
+    const list = attributes[listKey];
+    if (!Array.isArray(list)) {
+      continue;
+    }
+    for (const item of list) {
+      pushScalarTag(categories, item);
+    }
+  }
+  for (const [key, value] of Object.entries(attributes)) {
+    if (SKIP_ATTRIBUTE_KEYS.has(key)) {
+      continue;
+    }
+    if (typeof value === "boolean") {
+      if (value) {
+        categories.push(key);
+      }
+      continue;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (typeof item === "boolean") {
+          if (item) {
+            categories.push(`${key}:true`);
+          }
+          continue;
+        }
+        if (item !== void 0 && item !== null && item !== "") {
+          categories.push(`${key}:${String(item)}`);
+        }
+      }
+      continue;
+    }
+    if (value !== void 0 && value !== null && value !== "") {
+      if (typeof value === "string" || typeof value === "number" || typeof value === "bigint") {
+        categories.push(`${key}:${String(value)}`);
+      }
+    }
+  }
+  const lat = firstNumber(attributes, ["latitude", "lat"]);
+  const lon = firstNumber(attributes, ["longitude", "lng", "lon"]);
+  if (lat !== void 0 && lon !== void 0) {
+    categories.push(...GeoHash.encodeMultiTags(lat, lon));
+  }
+  return [...new Set(categories)];
+}
+function firstNumber(source, keys) {
+  for (const key of keys) {
+    const value = source[key];
+    if (value === void 0 || value === null || value === "") {
+      continue;
+    }
+    const numeric = typeof value === "number" ? value : Number(value);
+    if (Number.isFinite(numeric)) {
+      return numeric;
+    }
+  }
+  return void 0;
+}
+function firstString(source, keys) {
+  for (const key of keys) {
+    const value = source[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+  return void 0;
+}
+function encodeEntity(entityIdOrInput, attributes = {}, defaults = {}) {
+  const isObjectInput = typeof entityIdOrInput === "object" && entityIdOrInput !== null && !Array.isArray(entityIdOrInput);
+  const input = isObjectInput ? entityIdOrInput : {};
+  const nested = asRecord(input.attributes);
+  const merged = {
+    ...input,
+    ...nested,
+    ...attributes
+  };
+  const rawId = (!isObjectInput ? entityIdOrInput : void 0) ?? input.id ?? input.entityId ?? input.entity_id ?? nested.id ?? nested.entityId ?? nested.entity_id;
+  if (rawId === void 0 || rawId === null || rawId === "") {
+    throw new PulseIndexQueryError("entityId is required.");
+  }
+  const tenantId = firstString(merged, ["tenantId", "tenant_id"]) ?? defaults.tenantId ?? "";
+  return {
+    entityId: toUint64String(rawId, "entityId"),
+    categories: flattenAttributes(merged),
+    price: toUint32(merged.price, "price"),
+    locationPrefix: toUint64String(
+      merged.locationPrefix ?? merged.location_prefix ?? 0,
+      "locationPrefix"
+    ),
+    tenantId
+  };
+}
+
+// src/client/PulseIndexClient.ts
+var PulseIndexClient = class _PulseIndexClient {
+  connection;
+  constructor(config = {}) {
+    this.connection = new ConnectionManager(config);
+  }
+  static create(endpoint, apiKey, ssl, extra = {}) {
+    return new _PulseIndexClient({
+      ...extra,
+      endpoint,
+      apiKey,
+      ssl
+    });
+  }
+  static query() {
+    return new QueryBuilder();
+  }
+  query() {
+    return new QueryBuilder(this);
+  }
+  async search(query) {
+    const builder = query instanceof QueryBuilder ? query : QueryBuilder.fromOptions(query, this);
+    const raw = await this.unary(
+      (stub, metadata, options, callback) => stub.search(builder.toRequest(this.connection.tenantId), metadata, options, callback)
+    );
+    return {
+      matchedEntityIds: (raw.matchedEntityIds ?? []).map((id) => String(id)),
+      totalMatches: Number(raw.totalMatches ?? 0),
+      executionTimeUs: Number(raw.executionTimeUs ?? 0)
+    };
+  }
+  async index(entityIdOrInput, attributes = {}) {
+    const encoded = encodeEntity(entityIdOrInput, attributes, {
+      tenantId: this.connection.tenantId
+    });
+    const raw = await this.unary(
+      (stub, metadata, options, callback) => stub.indexEntity(toIndexRequest(encoded), metadata, options, callback)
+    );
+    return { success: Boolean(raw.success) };
+  }
+  async indexEntity(entityId, categories = [], price = 0, locationPrefix = 0, tenantId = "") {
+    const response = await this.index({
+      entityId,
+      categories,
+      price,
+      locationPrefix,
+      tenantId: tenantId || this.connection.tenantId
+    });
+    return response.success;
+  }
+  async batchIndex(entities) {
+    const requests = entities.map(
+      (entity) => toIndexRequest(
+        encodeEntity(entity, {}, { tenantId: this.connection.tenantId })
+      )
+    );
+    const raw = await this.unary(
+      (stub, metadata, options, callback) => stub.batchIndexEntities({ entities: requests }, metadata, options, callback)
+    );
+    return { indexedCount: Number(raw.indexedCount ?? 0) };
+  }
+  async delete(entityId, tenantId) {
+    const raw = await this.unary(
+      (stub, metadata, options, callback) => stub.deleteEntity(
+        {
+          entityId: toUint64String(entityId, "entityId"),
+          tenantId: tenantId ?? this.connection.tenantId
+        },
+        metadata,
+        options,
+        callback
+      )
+    );
+    return { success: Boolean(raw.success) };
+  }
+  async deleteEntity(entityId, tenantId = "") {
+    const response = await this.delete(entityId, tenantId || this.connection.tenantId);
+    return response.success;
+  }
+  /**
+   * True only when the engine can serve reads.
+   *
+   * Asks `grpc.health.v1.Health`, which needs no particular scope and tracks
+   * whether the service can currently answer queries. So this distinguishes a
+   * reachable-but-unavailable service from a healthy one.
+   *
+   * Returns `false` rather than throwing, so unreachable and unavailable look
+   * the same here. Use {@link servingStatus} to tell them apart.
+   */
+  async health() {
+    try {
+      await this.connection.waitForReady();
+      const status2 = await this.servingStatus();
+      return status2 === SERVING_STATUS.SERVING;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Raw `grpc.health.v1` serving status for a service name.
+   *
+   * Defaults to `''`, the overall-server key defined by the health spec. The
+   * service answers for both that and its named service.
+   */
+  async servingStatus(service = "") {
+    const stub = this.connection.getHealthStub();
+    return new Promise((resolve, reject) => {
+      stub.check(
+        { service },
+        this.connection.createMetadata(),
+        this.connection.createCallOptions(),
+        (error, response) => {
+          if (error) {
+            reject(PulseIndexError.fromGrpc(error));
+            return;
+          }
+          resolve(response?.status ?? SERVING_STATUS.UNKNOWN);
+        }
+      );
+    });
+  }
+  close() {
+    this.connection.close();
+  }
+  unary(invoke) {
+    return new Promise((resolve, reject) => {
+      let stub;
+      try {
+        stub = this.connection.getStub();
+      } catch (error) {
+        reject(
+          error instanceof PulseIndexError ? error : new PulseIndexConnectionError("Failed to acquire a gRPC channel.", {
+            cause: error
+          })
+        );
+        return;
+      }
+      invoke(
+        stub,
+        this.connection.createMetadata(),
+        this.connection.createCallOptions(),
+        (error, response) => {
+          if (error) {
+            reject(PulseIndexError.fromGrpc(error));
+            return;
+          }
+          if (response === void 0 || response === null) {
+            reject(new PulseIndexError("Empty gRPC response."));
+            return;
+          }
+          resolve(response);
+        }
+      );
+    });
+  }
+};
+var PulseIndex = class extends PulseIndexClient {
+};
+function toIndexRequest(encoded) {
+  return {
+    entityId: encoded.entityId,
+    locationPrefix: encoded.locationPrefix,
+    price: encoded.price,
+    categories: encoded.categories,
+    tenantId: encoded.tenantId
+  };
+}
+
+// src/index.ts
+var index_default = PulseIndex;
+
+exports.ConnectionManager = ConnectionManager;
+exports.FilterOperation = FilterOperation;
+exports.GeoHash = GeoHash;
+exports.PulseIndex = PulseIndex;
+exports.PulseIndexAuthError = PulseIndexAuthError;
+exports.PulseIndexClient = PulseIndexClient;
+exports.PulseIndexConnectionError = PulseIndexConnectionError;
+exports.PulseIndexError = PulseIndexError;
+exports.PulseIndexQueryError = PulseIndexQueryError;
+exports.QueryBuilder = QueryBuilder;
+exports.SERVING_STATUS = SERVING_STATUS;
+exports.default = index_default;
+exports.encodeEntity = encodeEntity;
+exports.sslEnabled = sslEnabled;
+exports.toUint64String = toUint64String;