@happyvertical/smrt-places 0.30.0

package/dist/index.js

@@ -0,0 +1,966 @@
+import { ObjectRegistry, foreignKey, crossPackageRef, field, smrt, SmrtObject, SmrtJunction, SmrtHierarchical, SmrtCollection } from "@happyvertical/smrt-core";
+import { getOwnedAssetsFromCollection, addOwnedAssetFromCollection, removeOwnedAssetFromCollection, resolveOwnedAssetsById, assertValidOwnedAssetRelationship, assertValidOwnedAssetSortOrder } from "@happyvertical/smrt-assets";
+import { tenantId, TenantScoped } from "@happyvertical/smrt-tenancy";
+import { getGeoAdapter } from "@happyvertical/geo";
+import { areCoordinatesNear, calculateDistance, formatCoordinates, generateDisplayName, locationToGeoData, mapLocationTypeToPlaceType, normalizeAddressComponents, parseCoordinates, validateCoordinates } from "./utils.js";
+ObjectRegistry.registerPackageManifest(
+  new URL("./manifest.json", import.meta.url)
+);
+var __defProp$3 = Object.defineProperty;
+var __getOwnPropDesc$3 = Object.getOwnPropertyDescriptor;
+var __decorateClass$3 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$3(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp$3(target, key, result);
+  return result;
+};
+let PlaceAsset = class extends SmrtObject {
+  tenantId = null;
+  placeId = "";
+  assetId = "";
+  relationship = "attachment";
+  sortOrder = 0;
+  constructor(options = {}) {
+    super(options);
+    if (options.placeId) this.placeId = options.placeId;
+    if (options.assetId) this.assetId = options.assetId;
+    if (options.relationship) this.relationship = options.relationship;
+    if (options.sortOrder !== void 0) this.sortOrder = options.sortOrder;
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+  }
+};
+__decorateClass$3([
+  tenantId({ nullable: true })
+], PlaceAsset.prototype, "tenantId", 2);
+__decorateClass$3([
+  foreignKey("Place", { required: true })
+], PlaceAsset.prototype, "placeId", 2);
+__decorateClass$3([
+  crossPackageRef("@happyvertical/smrt-assets:Asset", { required: true })
+], PlaceAsset.prototype, "assetId", 2);
+__decorateClass$3([
+  field({ required: true })
+], PlaceAsset.prototype, "relationship", 2);
+__decorateClass$3([
+  field()
+], PlaceAsset.prototype, "sortOrder", 2);
+PlaceAsset = __decorateClass$3([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    tableName: "place_assets",
+    conflictColumns: ["place_id", "asset_id", "relationship"],
+    api: false,
+    mcp: false,
+    cli: false
+  })
+], PlaceAsset);
+var __defProp$2 = Object.defineProperty;
+var __getOwnPropDesc$2 = Object.getOwnPropertyDescriptor;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp$2(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __decorateClass$2 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$2(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = decorator(result) || result;
+  return result;
+};
+var __publicField = (obj, key, value) => __defNormalProp(obj, key + "", value);
+let PlaceAssetCollection = class extends SmrtJunction {
+  leftField = "placeId";
+  rightField = "assetId";
+  placeCollectionPromise = null;
+  async getPlaceCollection() {
+    if (!this.placeCollectionPromise) {
+      const { PlaceCollection: PlaceCollection2 } = await Promise.resolve().then(() => PlaceCollection$1);
+      this.placeCollectionPromise = PlaceCollection2.create({ db: this.db });
+    }
+    return this.placeCollectionPromise;
+  }
+  async getAssets(placeId, relationship) {
+    return getOwnedAssetsFromCollection(
+      await this.getPlaceCollection(),
+      placeId,
+      relationship
+    );
+  }
+  async addAsset(placeId, asset, relationship = "attachment", sortOrder = 0) {
+    await addOwnedAssetFromCollection(
+      await this.getPlaceCollection(),
+      "Place",
+      placeId,
+      asset,
+      relationship,
+      sortOrder
+    );
+  }
+  async removeAsset(placeId, assetId, relationship) {
+    await removeOwnedAssetFromCollection(
+      await this.getPlaceCollection(),
+      "Place",
+      placeId,
+      assetId,
+      relationship
+    );
+  }
+};
+__publicField(PlaceAssetCollection, "_itemClass", PlaceAsset);
+PlaceAssetCollection = __decorateClass$2([
+  smrt({
+    api: false,
+    mcp: false,
+    cli: false
+  })
+], PlaceAssetCollection);
+const PlaceAssetCollection$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  get PlaceAssetCollection() {
+    return PlaceAssetCollection;
+  }
+}, Symbol.toStringTag, { value: "Module" }));
+var __defProp$1 = Object.defineProperty;
+var __getOwnPropDesc$1 = Object.getOwnPropertyDescriptor;
+var __decorateClass$1 = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc$1(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp$1(target, key, result);
+  return result;
+};
+let Place = class extends SmrtHierarchical {
+  tenantId = null;
+  typeId = "";
+  // FK to PlaceType
+  // parentId inherited from SmrtHierarchical (nullable, self-reference)
+  name = "";
+  // Place name/title
+  description = "";
+  latitude = null;
+  longitude = null;
+  streetNumber = "";
+  streetName = "";
+  city = "";
+  region = "";
+  country = "";
+  postalCode = "";
+  countryCode = "";
+  timezone = "";
+  // Metadata
+  externalId = "";
+  // External system identifier
+  source = "";
+  // Where this place came from (e.g., 'google', 'osm')
+  metadata = "";
+  // JSON metadata stored as text
+  // Timestamps
+  createdAt = /* @__PURE__ */ new Date();
+  updatedAt = /* @__PURE__ */ new Date();
+  constructor(options = {}) {
+    super(options);
+    if (options.tenantId !== void 0) this.tenantId = options.tenantId;
+    if (options.typeId) this.typeId = options.typeId;
+    if (options.parentId !== void 0)
+      this.parentId = options.parentId ?? null;
+    if (options.name) this.name = options.name;
+    if (options.description !== void 0)
+      this.description = options.description;
+    if (options.latitude !== void 0) this.latitude = options.latitude;
+    if (options.longitude !== void 0) this.longitude = options.longitude;
+    if (options.streetNumber !== void 0)
+      this.streetNumber = options.streetNumber;
+    if (options.streetName !== void 0) this.streetName = options.streetName;
+    if (options.city !== void 0) this.city = options.city;
+    if (options.region !== void 0) this.region = options.region;
+    if (options.country !== void 0) this.country = options.country;
+    if (options.postalCode !== void 0) this.postalCode = options.postalCode;
+    if (options.countryCode !== void 0)
+      this.countryCode = options.countryCode;
+    if (options.timezone !== void 0) this.timezone = options.timezone;
+    if (options.externalId !== void 0) this.externalId = options.externalId;
+    if (options.source !== void 0) this.source = options.source;
+    if (options.metadata !== void 0) {
+      if (typeof options.metadata === "string") {
+        this.metadata = options.metadata;
+      } else {
+        this.metadata = JSON.stringify(options.metadata);
+      }
+    }
+    if (options.createdAt) this.createdAt = options.createdAt;
+    if (options.updatedAt) this.updatedAt = options.updatedAt;
+  }
+  /**
+   * Get geographic data for this place
+   *
+   * @returns GeoData object with all geo fields
+   */
+  getGeoData() {
+    return {
+      latitude: this.latitude,
+      longitude: this.longitude,
+      streetNumber: this.streetNumber || void 0,
+      streetName: this.streetName || void 0,
+      city: this.city || void 0,
+      region: this.region || void 0,
+      country: this.country || void 0,
+      postalCode: this.postalCode || void 0,
+      countryCode: this.countryCode || void 0,
+      timezone: this.timezone || void 0
+    };
+  }
+  /**
+   * Check if this place has geographic coordinates
+   *
+   * @returns True if latitude and longitude are set
+   */
+  hasCoordinates() {
+    return this.latitude !== null && this.longitude !== null;
+  }
+  /**
+   * Get metadata as parsed object
+   *
+   * @returns Parsed metadata object or empty object if no metadata
+   */
+  getMetadata() {
+    if (!this.metadata) return {};
+    try {
+      return JSON.parse(this.metadata);
+    } catch {
+      return {};
+    }
+  }
+  /**
+   * Set metadata from object
+   *
+   * @param data - Metadata object to store
+   */
+  setMetadata(data) {
+    this.metadata = JSON.stringify(data);
+  }
+  /**
+   * Update metadata by merging with existing values
+   *
+   * @param updates - Partial metadata to merge
+   */
+  updateMetadata(updates) {
+    const current = this.getMetadata();
+    this.setMetadata({ ...current, ...updates });
+  }
+  /**
+   * Get the place type
+   *
+   * @returns PlaceType instance or null if not found
+   */
+  async getType() {
+    if (!this.typeId) return null;
+    const { PlaceTypeCollection: PlaceTypeCollection2 } = await Promise.resolve().then(() => PlaceTypeCollection$1);
+    const collection = await PlaceTypeCollection2.create(this.options);
+    return await collection.get({ id: this.typeId });
+  }
+  // Hierarchy traversal (getParent / getChildren / getAncestors /
+  // getDescendants / getHierarchy / moveTo) provided by SmrtHierarchical.
+  async getPlaceAssetCollection() {
+    const { PlaceAssetCollection: PlaceAssetCollection2 } = await Promise.resolve().then(() => PlaceAssetCollection$1);
+    return PlaceAssetCollection2.create({ db: this.db });
+  }
+  async getAssets(relationship) {
+    if (!this.id) {
+      return [];
+    }
+    const placeAssets = await this.getPlaceAssetCollection();
+    const linkedAssets = await placeAssets.byLeft(
+      this.id,
+      relationship ? { relationship } : {}
+    );
+    return resolveOwnedAssetsById(
+      this.db,
+      linkedAssets.map((link) => link.assetId),
+      this.tenantId
+    );
+  }
+  async addAsset(asset, relationship = "attachment", sortOrder = 0) {
+    if (!this.id || !asset.id) {
+      throw new Error("Cannot associate unsaved place or asset");
+    }
+    assertValidOwnedAssetRelationship(relationship);
+    assertValidOwnedAssetSortOrder(sortOrder);
+    const placeAssets = await this.getPlaceAssetCollection();
+    await placeAssets.attach(this.id, asset.id, {
+      relationship,
+      sortOrder,
+      tenantId: this.tenantId
+    });
+  }
+  async removeAsset(assetId, relationship) {
+    if (!this.id) {
+      return;
+    }
+    const placeAssets = await this.getPlaceAssetCollection();
+    await placeAssets.detach(
+      this.id,
+      assetId,
+      relationship ? { relationship } : {}
+    );
+  }
+};
+__decorateClass$1([
+  tenantId({ nullable: true })
+], Place.prototype, "tenantId", 2);
+__decorateClass$1([
+  foreignKey("PlaceType")
+], Place.prototype, "typeId", 2);
+__decorateClass$1([
+  field({ type: "decimal" })
+], Place.prototype, "latitude", 2);
+__decorateClass$1([
+  field({ type: "decimal" })
+], Place.prototype, "longitude", 2);
+Place = __decorateClass$1([
+  TenantScoped({ mode: "optional" }),
+  smrt({
+    tableStrategy: "sti",
+    api: { include: ["list", "get", "create", "update", "delete"] },
+    mcp: { include: ["list", "get", "create", "update"] },
+    cli: true
+  })
+], Place);
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+let PlaceType = class extends SmrtObject {
+  name = "";
+  // Type name (e.g., 'Town', 'City', 'Country')
+  description;
+  // Optional description
+  // Timestamps
+  createdAt = /* @__PURE__ */ new Date();
+  updatedAt = /* @__PURE__ */ new Date();
+  constructor(options = {}) {
+    super(options);
+    if (options.name) this.name = options.name;
+    if (options.description !== void 0)
+      this.description = options.description;
+    if (options.createdAt) this.createdAt = options.createdAt;
+    if (options.updatedAt) this.updatedAt = options.updatedAt;
+  }
+  /**
+   * Convenience method for slug-based lookup
+   *
+   * @param slug - The slug to search for
+   * @returns PlaceType instance or null if not found
+   */
+  static async getBySlug(_slug) {
+    return null;
+  }
+};
+__decorateClass([
+  field({ required: true })
+], PlaceType.prototype, "name", 2);
+PlaceType = __decorateClass([
+  smrt({
+    tableStrategy: "sti",
+    api: { include: ["list", "get", "create", "update", "delete"] },
+    mcp: { include: ["list", "get", "create"] },
+    cli: true
+  })
+], PlaceType);
+class PlaceTypeCollection extends SmrtCollection {
+  static _itemClass = PlaceType;
+  /**
+   * Get or create a place type by slug
+   *
+   * @param slug - PlaceType slug (e.g., 'city', 'building')
+   * @param name - Optional display name (defaults to capitalized slug)
+   * @returns PlaceType instance
+   */
+  async getOrCreate(slug, name) {
+    const existing = await this.get({ slug });
+    if (existing) {
+      return existing;
+    }
+    const displayName = name || slug.replace(/-/g, " ").replace(/\b\w/g, (l) => l.toUpperCase());
+    return await this.create({
+      slug,
+      name: displayName
+    });
+  }
+  /**
+   * Get a place type by slug
+   *
+   * @param slug - PlaceType slug to search for
+   * @returns PlaceType instance or null if not found
+   */
+  async getBySlug(slug) {
+    return await this.get({ slug });
+  }
+  /**
+   * Initialize default place types
+   *
+   * Creates standard types if they don't exist:
+   * - country
+   * - region (state/province)
+   * - city
+   * - address
+   * - building
+   * - room
+   * - zone (for abstract/virtual places)
+   *
+   * @returns Array of created/existing place types
+   */
+  async initializeDefaults() {
+    const defaults = [
+      { slug: "country", name: "Country" },
+      { slug: "region", name: "Region" },
+      { slug: "city", name: "City" },
+      { slug: "address", name: "Address" },
+      { slug: "building", name: "Building" },
+      { slug: "room", name: "Room" },
+      { slug: "zone", name: "Zone" },
+      { slug: "point_of_interest", name: "Point of Interest" }
+    ];
+    const types = [];
+    for (const def of defaults) {
+      const type = await this.getOrCreate(def.slug, def.name);
+      types.push(type);
+    }
+    return types;
+  }
+}
+const PlaceTypeCollection$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  PlaceTypeCollection
+}, Symbol.toStringTag, { value: "Module" }));
+class PlaceCollection extends SmrtCollection {
+  static _itemClass = Place;
+  /**
+   * Look up a place by query or coordinates, creating it if not found
+   *
+   * This is the key method for organic database growth:
+   * 1. Search local database first
+   * 2. If not found, query @happyvertical/geo
+   * 3. Create place from geocoding result
+   * 4. Return place
+   *
+   * @param query - Address or location query string
+   * @param options - Lookup options (provider, type, parent, etc.)
+   * @returns Place instance
+   */
+  async lookupOrCreate(query, options = {}) {
+    const {
+      geoProvider = "openstreetmap",
+      typeSlug,
+      parentId,
+      createIfNotFound = true,
+      coords
+    } = options;
+    let existingPlace = null;
+    if (coords) {
+      existingPlace = await this.findByCoordinates(coords.lat, coords.lng);
+    }
+    if (!existingPlace) {
+      existingPlace = await this.findByQuery(query);
+    }
+    if (existingPlace) {
+      return existingPlace;
+    }
+    if (!createIfNotFound) {
+      return null;
+    }
+    const locations = await this.geocode(
+      query,
+      coords,
+      geoProvider
+    );
+    if (locations.length === 0) {
+      return null;
+    }
+    const location = locations[0];
+    return await this.createFromLocation(location, typeSlug, parentId);
+  }
+  /**
+   * Find place by coordinates (within small threshold)
+   *
+   * @param latitude - Latitude to search
+   * @param longitude - Longitude to search
+   * @param threshold - Max distance in degrees (default: 0.0001 ~11m)
+   * @returns Place instance or null
+   */
+  async findByCoordinates(latitude, longitude, threshold = 1e-4) {
+    const places = await this.list({
+      where: {
+        latitude: { $ne: null },
+        longitude: { $ne: null }
+      }
+    });
+    for (const place of places) {
+      const placeObj = place;
+      if (placeObj.latitude === null || placeObj.longitude === null) continue;
+      const latDiff = Math.abs(placeObj.latitude - latitude);
+      const lngDiff = Math.abs(placeObj.longitude - longitude);
+      if (latDiff < threshold && lngDiff < threshold) {
+        return place;
+      }
+    }
+    return null;
+  }
+  /**
+   * Find place by query text (matches name, city, region, country)
+   *
+   * @param query - Search query
+   * @returns Place instance or null
+   */
+  async findByQuery(query) {
+    const normalizedQuery = query.toLowerCase().trim();
+    const places = await this.list({});
+    for (const place of places) {
+      if (place.name.toLowerCase().includes(normalizedQuery)) {
+        return place;
+      }
+      const addressParts = [
+        place.streetNumber,
+        place.streetName,
+        place.city,
+        place.region,
+        place.country
+      ].filter((p) => p).join(" ").toLowerCase();
+      if (addressParts.includes(normalizedQuery)) {
+        return place;
+      }
+    }
+    return null;
+  }
+  /**
+   * Geocode query or coordinates using @happyvertical/geo
+   *
+   * @param query - Address query
+   * @param coords - Optional coordinates for reverse geocoding
+   * @param provider - Geo provider to use
+   * @returns Array of Location results
+   */
+  async geocode(query, coords, provider = "openstreetmap") {
+    const geo = await this.getGeoAdapter(provider);
+    if (coords) {
+      return await geo.reverseGeocode(coords.lat, coords.lng);
+    }
+    return await geo.lookup(query);
+  }
+  /**
+   * Find a place by the provider's native id (Google place_id, OSM
+   * osm-node-N, etc.). Used as the primary idempotency key by
+   * `discoverNearby` so repeat POI searches don't create duplicate rows.
+   */
+  async findByExternalId(externalId) {
+    if (!externalId) return null;
+    const matches = await this.list({
+      where: { externalId },
+      limit: 1
+    });
+    return matches[0] ?? null;
+  }
+  /**
+   * Idempotent "find or create" for a geo Location. Keyed purely on the
+   * provider's externalId (Google place_id, osm-node-*, etc.), which is
+   * stable per POI across repeat searches. The older `lookupOrCreate`
+   * keeps its own fallback chain (name/address/coordinate matching) for
+   * address-style workflows where externalId isn't reliable.
+   *
+   * Returns `{ place, created }` so callers can distinguish fresh rows
+   * from reused ones without re-querying the table — this is how
+   * `resolveTrackPlaces` derives its `cacheHitCount` without a full
+   * scan per bucket.
+   */
+  async ensureFromLocation(location, typeSlug, parentId) {
+    if (location.id) {
+      const existing = await this.findByExternalId(location.id);
+      if (existing) return { place: existing, created: false };
+    }
+    const place = await this.createFromLocation(location, typeSlug, parentId);
+    return { place, created: true };
+  }
+  /**
+   * Create place from @happyvertical/geo Location data
+   *
+   * @param location - Location from geocoding
+   * @param typeSlug - Optional type slug override
+   * @param parentId - Optional parent place ID
+   * @returns Created Place instance
+   */
+  async createFromLocation(location, typeSlug, parentId) {
+    const typeCollection = await PlaceTypeCollection.create(
+      this.options
+    );
+    const slug = typeSlug || location.type || "address";
+    const placeType = await typeCollection.getOrCreate(slug);
+    const components = location.addressComponents || {};
+    return await this.create({
+      typeId: placeType.id,
+      parentId: parentId ?? null,
+      name: location.name,
+      description: "",
+      // Geo fields from location
+      latitude: location.latitude,
+      longitude: location.longitude,
+      streetNumber: components.streetNumber || "",
+      streetName: components.streetName || "",
+      city: components.city || "",
+      region: components.region || "",
+      country: components.country || "",
+      postalCode: components.postalCode || "",
+      countryCode: location.countryCode || "",
+      timezone: location.timezone || "",
+      // Metadata
+      externalId: location.id,
+      source: location.raw?.provider || "unknown",
+      metadata: JSON.stringify({ raw: location.raw ?? null })
+    });
+  }
+  /**
+   * Discover POIs near a coordinate and persist them as Place rows.
+   *
+   * Composes `@happyvertical/geo`'s `findPoisNear` with `ensureFromLocation`
+   * so every returned POI is either reused from the local DB (when the
+   * provider returns an id matching an existing Place `externalId`) or
+   * created fresh otherwise. The cache is effectively automatic because
+   * the provider's own place_id becomes the Place row's `externalId`, so
+   * calling `discoverNearby` twice for the same area on the same provider
+   * is a no-op after the first run when the provider returns stable ids.
+   *
+   * Requires a geo provider that implements `findPoisNear`. Throws a clear
+   * error otherwise so consumers can fall back to `lookupOrCreate` or
+   * switch providers.
+   */
+  async discoverNearby(latitude, longitude, radiusMeters, options = {}) {
+    if (!(radiusMeters > 0)) {
+      throw new Error(
+        `discoverNearby: radiusMeters must be > 0 (got ${radiusMeters})`
+      );
+    }
+    const detailed = await this.discoverNearbyDetailed(
+      latitude,
+      longitude,
+      radiusMeters,
+      options
+    );
+    return detailed.map((d) => d.place);
+  }
+  /**
+   * Internal variant of `discoverNearby` that exposes whether each
+   * returned Place was created during this call (`true`) or reused from
+   * an earlier call (`false`). Used by `resolveTrackPlaces` to classify
+   * buckets as cache hits without having to re-scan the Place table.
+   */
+  async discoverNearbyDetailed(latitude, longitude, radiusMeters, options = {}) {
+    const {
+      geoProvider = "openstreetmap",
+      types,
+      keyword,
+      limit,
+      language,
+      typeSlug,
+      parentId
+    } = options;
+    const geo = await this.getGeoAdapter(geoProvider);
+    if (typeof geo.findPoisNear !== "function") {
+      throw new Error(
+        `Geo provider '${geoProvider}' does not implement findPoisNear`
+      );
+    }
+    const results = await geo.findPoisNear(latitude, longitude, radiusMeters, {
+      types,
+      keyword,
+      limit,
+      language
+    });
+    const detailed = [];
+    for (const result of results) {
+      detailed.push(await this.ensureFromLocation(result, typeSlug, parentId));
+    }
+    return detailed;
+  }
+  /**
+   * Resolve POIs along a GPS track (e.g. a video's per-frame path).
+   *
+   * Naively walking every point would hammer the provider with redundant
+   * requests — consecutive samples are usually within a few meters. This
+   * method buckets points into a `bucketMeters`-wide grid, calls
+   * `discoverNearby` once per distinct bucket, and throttles requests per
+   * `throttleMs` so free tiers (Overpass, Nominatim) stay inside their
+   * community rate limits without the caller having to manage a queue.
+   *
+   * The returned `places` are deduped across buckets by Place id, so a
+   * POI that falls within several overlapping search radii appears once.
+   */
+  async resolveTrackPlaces(points, options = {}) {
+    const radiusMeters = options.radiusMeters ?? 50;
+    const bucketMeters = options.bucketMeters ?? 50;
+    const throttleMs = options.throttleMs ?? 1100;
+    if (!(radiusMeters > 0)) {
+      throw new Error(
+        `resolveTrackPlaces: radiusMeters must be > 0 (got ${radiusMeters})`
+      );
+    }
+    if (!(bucketMeters > 0)) {
+      throw new Error(
+        `resolveTrackPlaces: bucketMeters must be > 0 (got ${bucketMeters})`
+      );
+    }
+    if (throttleMs < 0 || !Number.isFinite(throttleMs)) {
+      throw new Error(
+        `resolveTrackPlaces: throttleMs must be a finite non-negative number (got ${throttleMs})`
+      );
+    }
+    const bucketMetersKm = bucketMeters / 1e3;
+    const bucketCenters = [];
+    for (const point of points) {
+      if (!Number.isFinite(point.lat) || !Number.isFinite(point.lng)) continue;
+      let bestIdx = -1;
+      let bestKm = Number.POSITIVE_INFINITY;
+      for (let i = 0; i < bucketCenters.length; i += 1) {
+        const c = bucketCenters[i];
+        const km = this.calculateDistance(c.lat, c.lng, point.lat, point.lng);
+        if (km <= bucketMetersKm && km < bestKm) {
+          bestKm = km;
+          bestIdx = i;
+        }
+      }
+      if (bestIdx < 0) bucketCenters.push(point);
+    }
+    const result = {
+      places: [],
+      requestCount: 0,
+      cacheHitCount: 0,
+      bucketCount: bucketCenters.length
+    };
+    const seen = /* @__PURE__ */ new Map();
+    let lastCallAt = 0;
+    for (const center of bucketCenters) {
+      const wait = lastCallAt + throttleMs - Date.now();
+      if (wait > 0) {
+        await new Promise((resolve) => setTimeout(resolve, wait));
+      }
+      const detailed = await this.discoverNearbyDetailed(
+        center.lat,
+        center.lng,
+        radiusMeters,
+        options
+      );
+      lastCallAt = Date.now();
+      result.requestCount += 1;
+      if (detailed.length > 0 && detailed.every((d) => !d.created)) {
+        result.cacheHitCount += 1;
+      }
+      for (const { place } of detailed) {
+        if (place.id && !seen.has(place.id)) seen.set(place.id, place);
+      }
+    }
+    result.places = [...seen.values()];
+    return result;
+  }
+  /**
+   * Provider wiring (env keys, user-agent string, etc.) that `geocode`
+   * and `discoverNearby` share so the two code paths can't drift. Kept
+   * separate from the adapter call itself so tests and future providers
+   * can inspect or override the options before construction.
+   */
+  getGeoAdapterOptions(provider) {
+    if (provider === "google") {
+      return {
+        provider: "google",
+        apiKey: process.env.GOOGLE_MAPS_API_KEY || ""
+      };
+    }
+    return { provider: "openstreetmap", userAgent: "@have/places" };
+  }
+  /**
+   * Build a geo adapter configured for this call. Single source of truth
+   * for provider wiring — `geocode` and `discoverNearby` both come through
+   * here.
+   */
+  async getGeoAdapter(provider) {
+    return getGeoAdapter(this.getGeoAdapterOptions(provider));
+  }
+  /**
+   * Get immediate children of a parent place
+   *
+   * @param parentId - The parent place ID
+   * @returns Array of child places
+   */
+  async getChildren(parentId) {
+    return await this.list({
+      where: { parentId }
+    });
+  }
+  /**
+   * Get root places (no parent)
+   *
+   * @returns Array of root places
+   */
+  async getRootPlaces() {
+    return await this.list({
+      where: { parentId: null }
+    });
+  }
+  /**
+   * Get places by type
+   *
+   * @param typeSlug - PlaceType slug
+   * @returns Array of places of that type
+   */
+  async getByType(typeSlug) {
+    const typeCollection = await PlaceTypeCollection.create(
+      this.options
+    );
+    const placeType = await typeCollection.getBySlug(typeSlug);
+    if (!placeType) return [];
+    return await this.list({
+      where: { typeId: placeType.id }
+    });
+  }
+  /**
+   * Get place hierarchy (all ancestors and descendants)
+   *
+   * @param placeId - The place ID
+   * @returns Object with ancestors, current place, and descendants
+   */
+  async getHierarchy(placeId) {
+    const place = await this.get({ id: placeId });
+    if (!place) throw new Error(`Place '${placeId}' not found`);
+    return await place.getHierarchy();
+  }
+  async getAssets(placeId, relationship) {
+    return getOwnedAssetsFromCollection(this, placeId, relationship);
+  }
+  async addAsset(placeId, asset, relationship = "attachment", sortOrder = 0) {
+    await addOwnedAssetFromCollection(
+      this,
+      "Place",
+      placeId,
+      asset,
+      relationship,
+      sortOrder
+    );
+  }
+  async removeAsset(placeId, assetId, relationship) {
+    await removeOwnedAssetFromCollection(
+      this,
+      "Place",
+      placeId,
+      assetId,
+      relationship
+    );
+  }
+  /**
+   * Search places by proximity to coordinates
+   *
+   * @param latitude - Center latitude
+   * @param longitude - Center longitude
+   * @param radiusKm - Search radius in kilometers
+   * @returns Array of places within radius, sorted by distance
+   */
+  async searchByProximity(latitude, longitude, radiusKm = 10) {
+    const places = await this.list({
+      where: {
+        latitude: { $ne: null },
+        longitude: { $ne: null }
+      }
+    });
+    const placesWithDistance = places.map((place) => {
+      if (place.latitude === null || place.longitude === null) return null;
+      const distance = this.calculateDistance(
+        latitude,
+        longitude,
+        place.latitude,
+        place.longitude
+      );
+      return { place, distance };
+    }).filter(
+      (p) => p !== null && p.distance <= radiusKm
+    ).sort((a, b) => a.distance - b.distance);
+    return placesWithDistance.map((p) => p.place);
+  }
+  /**
+   * Calculate distance between two coordinates using Haversine formula
+   *
+   * @param lat1 - First latitude
+   * @param lng1 - First longitude
+   * @param lat2 - Second latitude
+   * @param lng2 - Second longitude
+   * @returns Distance in kilometers
+   */
+  calculateDistance(lat1, lng1, lat2, lng2) {
+    const R = 6371;
+    const dLat = this.toRad(lat2 - lat1);
+    const dLng = this.toRad(lng2 - lng1);
+    const a = Math.sin(dLat / 2) * Math.sin(dLat / 2) + Math.cos(this.toRad(lat1)) * Math.cos(this.toRad(lat2)) * Math.sin(dLng / 2) * Math.sin(dLng / 2);
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return R * c;
+  }
+  /**
+   * Convert degrees to radians
+   */
+  toRad(degrees) {
+    return degrees * (Math.PI / 180);
+  }
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Tenant Helper Methods
+  // ─────────────────────────────────────────────────────────────────────────────
+  /**
+   * Find all places belonging to a specific tenant
+   *
+   * @param tenantId - The tenant ID to filter by
+   * @returns Array of places for the tenant
+   */
+  async findByTenant(tenantId2) {
+    return this.list({ where: { tenantId: tenantId2 } });
+  }
+  /**
+   * Find all global places (not associated with any tenant)
+   *
+   * @returns Array of global places
+   */
+  async findGlobal() {
+    return this.list({ where: { tenantId: null } });
+  }
+  /**
+   * Find places for a tenant including global places
+   *
+   * @param tenantId - The tenant ID to include
+   * @returns Array of tenant-specific and global places
+   */
+  async findWithGlobals(tenantId2) {
+    return this.query(
+      `SELECT * FROM ${this.tableName} WHERE tenant_id = ? OR tenant_id IS NULL`,
+      [tenantId2]
+    );
+  }
+}
+const PlaceCollection$1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  PlaceCollection
+}, Symbol.toStringTag, { value: "Module" }));
+export {
+  Place,
+  PlaceAsset,
+  PlaceAssetCollection,
+  PlaceCollection,
+  PlaceType,
+  PlaceTypeCollection,
+  areCoordinatesNear,
+  calculateDistance,
+  formatCoordinates,
+  generateDisplayName,
+  locationToGeoData,
+  mapLocationTypeToPlaceType,
+  normalizeAddressComponents,
+  parseCoordinates,
+  validateCoordinates
+};
+//# sourceMappingURL=index.js.map