@happyvertical/smrt-places 0.30.0

package/AGENTS.md

@@ -0,0 +1,29 @@
+# @happyvertical/smrt-places
+
+Hierarchical geographic database with organic growth via geocoding integration.
+
+## Models
+
+- **Place** (STI): hierarchical via `parentId`. Optional geo fields (all nullable — supports abstract places like game zones). `externalId`/`source` from geocoder. Metadata JSON.
+- **PlaceAsset**: dedicated owned-asset join in `place_assets` with `relationship` and `sortOrder`.
+- **PlaceType**: slug-based classification (country, city, building, zone, room, region).
+
+## Key Collection Methods
+
+| Method | Purpose |
+|--------|---------|
+| `lookupOrCreate(query)` | DB first → geocode if not found → create. Organic growth pattern. |
+| `findByCoordinates(lat, lng, threshold)` | Default 0.0001° ≈ 11m tolerance at equator |
+| `searchByProximity(lat, lng, radiusKm)` | Haversine distance, sorted by proximity |
+| `findWithGlobals(tenantId)` | Tenant + global (tenantId=null) places |
+| `getRootPlaces()`, `getByType(slug)` | Hierarchy + type queries |
+| `getAssets()` / `addAsset()` / `removeAsset()` | Owned asset helpers on both `Place` and `PlaceCollection`, backed by `place_assets` |
+
+Hierarchy traversal: `getParent()`, `getChildren()`, `getAncestors()`, `getDescendants()`, `getHierarchy()`.
+
+## Gotchas
+
+- **Geo providers**: Google Maps needs `GOOGLE_MAPS_API_KEY`; OpenStreetMap is default
+- **Abstract places allowed**: lat/lng nullable — supports non-geographic locations
+- **Coordinate tolerance varies by latitude**: 0.0001° ≈ 11m at equator, less at poles
+- **Optional tenancy** with nullable tenantId

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,185 @@
+# @happyvertical/smrt-places
+
+Hierarchical place management with geocoding integration and spatial queries. Supports both real-world locations (with coordinates) and abstract places (virtual worlds, game zones).
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-places
+```
+
+## Usage
+
+### Lookup or create places with organic database growth
+
+```typescript
+import { PlaceCollection, PlaceTypeCollection } from '@happyvertical/smrt-places';
+
+const places = await PlaceCollection.create();
+const types = await PlaceTypeCollection.create();
+
+// DB-first lookup, geocodes and creates if not found
+const place = await places.lookupOrCreate('1600 Amphitheatre Parkway, Mountain View, CA');
+
+if (place) {
+  console.log(`${place.name}: ${place.latitude}, ${place.longitude}`);
+  console.log(`Source: ${place.source}`); // 'openstreetmap' or 'google'
+}
+
+// Build hierarchy: Country > State > City
+const country = await places.create({
+  typeId: (await types.getOrCreate('country')).id,
+  name: 'United States',
+  countryCode: 'US',
+});
+
+const city = await places.create({
+  typeId: (await types.getOrCreate('city')).id,
+  parentId: country.id,
+  name: 'San Francisco',
+  latitude: 37.7749,
+  longitude: -122.4194,
+});
+
+// Hierarchy traversal
+const hierarchy = await city.getHierarchy();
+console.log(hierarchy.ancestors.map(p => p.name)); // ['United States']
+
+// Proximity search (Haversine distance, sorted nearest-first)
+const nearby = await places.searchByProximity(37.7749, -122.4194, 10); // 10km radius
+```
+
+### Discover POIs around a coordinate
+
+`discoverNearby` composes `@happyvertical/geo`'s `findPoisNear` with the
+collection's idempotent-persist logic. Each POI returned by the provider is
+either reused from the local DB (matched by provider `externalId`) or
+created as a fresh Place row. Repeat calls for the same area are effectively
+free — the provider's own id becomes `Place.externalId`, so a second scan
+doesn't duplicate anything.
+
+```typescript
+const pois = await places.discoverNearby(53.5461, -113.4938, 250, {
+  geoProvider: 'openstreetmap', // default
+  types: ['cafe'], // optional filter — passed through to the provider
+  limit: 10,
+});
+
+for (const poi of pois) {
+  console.log(poi.name, poi.externalId);
+}
+```
+
+Requires a geo provider that implements `findPoisNear`. Throws a clear error
+otherwise so callers can fall back to `lookupOrCreate` (address-level) or
+switch providers.
+
+### Resolve POIs along a GPS track
+
+For workflows like "what places does this drive/hike pass through?",
+`resolveTrackPlaces` walks an ordered array of points, collapses close
+samples into grid cells, throttles the provider between requests, and
+returns the deduplicated Place rows.
+
+```typescript
+const track = [
+  { lat: 53.5461, lng: -113.4938 },
+  { lat: 53.5465, lng: -113.4942 },
+  { lat: 53.5470, lng: -113.4950 },
+  // ...hundreds more along a route
+];
+
+const result = await places.resolveTrackPlaces(track, {
+  radiusMeters: 50,       // per-point POI search radius
+  bucketMeters: 50,       // collapse points within this distance into one request
+  throttleMs: 1100,       // ≥1s is safe for public Overpass/Nominatim
+  types: ['cafe', 'restaurant'],
+});
+
+console.log(`Hit ${result.requestCount} buckets, ${result.cacheHitCount} cached, ${result.places.length} distinct places`);
+```
+
+Bucketing is the main cost-saver: a 20-minute drive at 1 Hz GPS produces
+1200 raw samples but often only 100–200 distinct 50 m cells, so the
+provider only gets called 100–200 times. `throttleMs` keeps you within
+Overpass/Nominatim's 1 req/sec community limit out of the box; drop it to
+100 ms or so on paid tiers.
+
+### Owned assets
+
+```typescript
+import { AssetCollection } from '@happyvertical/smrt-assets';
+
+const assets = await AssetCollection.create();
+const floorplan = await assets.create({
+  name: 'main-hall-floorplan.png',
+  sourceUri: 'file:///tmp/main-hall-floorplan.png',
+  mimeType: 'image/png',
+});
+
+await place.addAsset(floorplan, 'floorplan');
+await places.addAsset(place.id!, floorplan, 'gallery', 1);
+
+const floorplans = await place.getAssets('floorplan');
+const galleryAssets = await places.getAssets(place.id!, 'gallery');
+```
+
+## API
+
+### Models
+
+| Export | Description |
+|--------|------------|
+| `Place` | Hierarchical place with optional geo fields, STI enabled |
+| `PlaceType` | Slug-based classification (country, city, building, zone, room) |
+| `PlaceAsset` | Dedicated owned-asset join stored in `place_assets` with `relationship` and `sortOrder` |
+
+### Collections
+
+| Export | Description |
+|--------|------------|
+| `PlaceCollection` | CRUD + `lookupOrCreate()`, `searchByProximity()`, `findByCoordinates()`, `getRootPlaces()`, `getByType()`, `findWithGlobals()` |
+| `PlaceAssetCollection` | Direct access to `place_assets` rows plus asset helper wrappers |
+| `PlaceTypeCollection` | CRUD + `getOrCreate()` for idempotent type creation |
+
+### Types
+
+| Export | Description |
+|--------|------------|
+| `GeoData` | Geographic data structure |
+| `LookupOrCreateOptions` | Options for `lookupOrCreate()` |
+| `PlaceHierarchy` | Hierarchy traversal result |
+| `PlaceOptions` | Place creation options |
+| `PlaceTypeOptions` | PlaceType creation options |
+
+### Utilities
+
+| Export | Description |
+|--------|------------|
+| `calculateDistance` | Haversine distance between two coordinates (km) |
+| `areCoordinatesNear` | Check if two coordinates are within threshold |
+| `validateCoordinates` | Validate lat/lng values |
+| `parseCoordinates` | Parse coordinate string to lat/lng |
+| `formatCoordinates` | Format lat/lng as string |
+| `generateDisplayName` | Build display name from address components |
+| `locationToGeoData` | Convert location response to GeoData |
+| `mapLocationTypeToPlaceType` | Map geocoder location type to PlaceType slug |
+| `normalizeAddressComponents` | Normalize address components from geocoder |
+
+### Instance Methods (Place)
+
+`getParent()`, `getChildren()`, `getAncestors()`, `getDescendants()`, `getHierarchy()` -- hierarchy traversal on any Place instance.
+
+Owned asset helpers are available on both `Place` and `PlaceCollection` via
+`getAssets()`, `addAsset()`, and `removeAsset()`. Common relationships include
+`hero`, `floorplan`, `gallery`, and `attachment`.
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@happyvertical/smrt-core` | SmrtObject/SmrtCollection base classes |
+| `@happyvertical/smrt-tenancy` | Optional tenant scoping |
+| `@happyvertical/geo` | Geocoding providers (OpenStreetMap, Google Maps) |
+| `@happyvertical/sql` | Database operations |
+| `@happyvertical/ai` | AI integration |