@happyvertical/smrt-places 0.51.32 → 0.51.33

package/dist/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../src/__smrt-register__.ts"],"names":[],"mappings":""}

package/dist/collections/PlaceAssetCollection.d.ts

@@ -0,0 +1,17 @@
+import type { Asset } from '@happyvertical/smrt-assets';
+import type { SmrtCollectionOptions } from '@happyvertical/smrt-core';
+import { SmrtJunction } from '@happyvertical/smrt-core';
+import { PlaceAsset } from '../models/PlaceAsset';
+export interface PlaceAssetCollectionOptions extends SmrtCollectionOptions {
+}
+export declare class PlaceAssetCollection extends SmrtJunction<PlaceAsset> {
+    static readonly _itemClass: typeof PlaceAsset;
+    protected leftField: string;
+    protected rightField: string;
+    private placeCollectionPromise;
+    private getPlaceCollection;
+    getAssets(placeId: string, relationship?: string): Promise<Asset[]>;
+    addAsset(placeId: string, asset: Asset, relationship?: string, sortOrder?: number): Promise<void>;
+    removeAsset(placeId: string, assetId: string, relationship?: string): Promise<void>;
+}
+//# sourceMappingURL=PlaceAssetCollection.d.ts.map

package/dist/collections/PlaceAssetCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlaceAssetCollection.d.ts","sourceRoot":"","sources":["../../src/collections/PlaceAssetCollection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAMxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,YAAY,EAAQ,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAGlD,MAAM,WAAW,2BAA4B,SAAQ,qBAAqB;CAAG;AAE7E,qBAKa,oBAAqB,SAAQ,YAAY,CAAC,UAAU,CAAC;IAChE,MAAM,CAAC,QAAQ,CAAC,UAAU,oBAAc;IACxC,SAAS,CAAC,SAAS,SAAa;IAChC,SAAS,CAAC,UAAU,SAAa;IAEjC,OAAO,CAAC,sBAAsB,CAAyC;YAEzD,kBAAkB;IAS1B,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAQnE,QAAQ,CACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,EACZ,YAAY,SAAe,EAC3B,SAAS,SAAI,GACZ,OAAO,CAAC,IAAI,CAAC;IAWV,WAAW,CACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC;CASjB"}

package/dist/collections/PlaceCollection.d.ts

@@ -0,0 +1,211 @@
+/**
+ * PlaceCollection - Collection manager for Place objects
+ *
+ * Provides hierarchy traversal and organic place database growth via
+ * lookupOrCreate method that integrates with @happyvertical/geo.
+ */
+import type { Asset } from '@happyvertical/smrt-assets';
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { Place } from '../models/Place';
+import type { DiscoverNearbyOptions, LookupOrCreateOptions, ResolveTrackPlacesOptions, TrackPlacesResult, TrackPoint } from '../types';
+export declare class PlaceCollection extends SmrtCollection<Place> {
+    static readonly _itemClass: typeof 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
+     */
+    lookupOrCreate(query: string, options?: LookupOrCreateOptions): Promise<Place | null>;
+    /**
+     * 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
+     */
+    private findByCoordinates;
+    /**
+     * Find place by query text (matches name, city, region, country)
+     *
+     * @param query - Search query
+     * @returns Place instance or null
+     */
+    private findByQuery;
+    /**
+     * 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
+     */
+    private geocode;
+    /**
+     * 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.
+     */
+    private findByExternalId;
+    /**
+     * 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.
+     */
+    private ensureFromLocation;
+    /**
+     * 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
+     */
+    private createFromLocation;
+    /**
+     * 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.
+     */
+    discoverNearby(latitude: number, longitude: number, radiusMeters: number, options?: DiscoverNearbyOptions): Promise<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.
+     */
+    private discoverNearbyDetailed;
+    /**
+     * 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.
+     */
+    resolveTrackPlaces(points: ReadonlyArray<TrackPoint>, options?: ResolveTrackPlacesOptions): Promise<TrackPlacesResult>;
+    /**
+     * 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.
+     */
+    private getGeoAdapterOptions;
+    /**
+     * Build a geo adapter configured for this call. Single source of truth
+     * for provider wiring — `geocode` and `discoverNearby` both come through
+     * here.
+     */
+    private getGeoAdapter;
+    /**
+     * Get immediate children of a parent place
+     *
+     * @param parentId - The parent place ID
+     * @returns Array of child places
+     */
+    getChildren(parentId: string): Promise<Place[]>;
+    /**
+     * Get root places (no parent)
+     *
+     * @returns Array of root places
+     */
+    getRootPlaces(): Promise<Place[]>;
+    /**
+     * Get places by type
+     *
+     * @param typeSlug - PlaceType slug
+     * @returns Array of places of that type
+     */
+    getByType(typeSlug: string): Promise<Place[]>;
+    /**
+     * Get place hierarchy (all ancestors and descendants)
+     *
+     * @param placeId - The place ID
+     * @returns Object with ancestors, current place, and descendants
+     */
+    getHierarchy(placeId: string): Promise<import("@happyvertical/smrt-core").HierarchyView<Place>>;
+    getAssets(placeId: string, relationship?: string): Promise<Asset[]>;
+    addAsset(placeId: string, asset: Asset, relationship?: string, sortOrder?: number): Promise<void>;
+    removeAsset(placeId: string, assetId: string, relationship?: string): Promise<void>;
+    /**
+     * 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
+     */
+    searchByProximity(latitude: number, longitude: number, radiusKm?: number): Promise<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
+     */
+    private calculateDistance;
+    /**
+     * Convert degrees to radians
+     */
+    private toRad;
+    /**
+     * Find all places belonging to a specific tenant
+     *
+     * @param tenantId - The tenant ID to filter by
+     * @returns Array of places for the tenant
+     */
+    findByTenant(tenantId: string): Promise<Place[]>;
+    /**
+     * Find all global places (not associated with any tenant).
+     *
+     * Routes through the shared tenant-global helper so it does not throw under
+     * an active tenant context (an explicit `tenant_id IS NULL` filter would be
+     * flagged as an isolation violation). (#1600)
+     *
+     * @returns Array of global places
+     */
+    findGlobal(): Promise<Place[]>;
+    /**
+     * Find places for a tenant including global places.
+     *
+     * Fails closed if an active tenant context requests a different tenant's
+     * rows; the admin/system path keeps the cross-tenant capability. (#1600)
+     *
+     * @param tenantId - The tenant ID to include
+     * @returns Array of tenant-specific and global places
+     */
+    findWithGlobals(tenantId: string): Promise<Place[]>;
+}
+//# sourceMappingURL=PlaceCollection.d.ts.map

package/dist/collections/PlaceCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlaceCollection.d.ts","sourceRoot":"","sources":["../../src/collections/PlaceCollection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AAMxD,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AACxC,OAAO,KAAK,EACV,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,EACjB,UAAU,EACX,MAAM,UAAU,CAAC;AAiBlB,qBAAa,eAAgB,SAAQ,cAAc,CAAC,KAAK,CAAC;IACxD,MAAM,CAAC,QAAQ,CAAC,UAAU,eAAS;IAEnC;;;;;;;;;;;;OAYG;IACG,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;IAiDxB;;;;;;;OAOG;YACW,iBAAiB;IA8B/B;;;;;OAKG;YACW,WAAW;IAgCzB;;;;;;;OAOG;YACW,OAAO;IAerB;;;;OAIG;YACW,gBAAgB;IAS9B;;;;;;;;;;;OAWG;YACW,kBAAkB;IAahC;;;;;;;OAOG;YACW,kBAAkB;IAwChC;;;;;;;;;;;;;;OAcG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,KAAK,EAAE,CAAC;IAenB;;;;;OAKG;YACW,sBAAsB;IAqCpC;;;;;;;;;;;;OAYG;IACG,kBAAkB,CACtB,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,EACjC,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,iBAAiB,CAAC;IAyF7B;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAc5B;;;;OAIG;YACW,aAAa;IAM3B;;;;;OAKG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAMrD;;;;OAIG;IACG,aAAa,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;IAMvC;;;;;OAKG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAYnD;;;;;OAKG;IACG,YAAY,CAAC,OAAO,EAAE,MAAM;IAO5B,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAInE,QAAQ,CACZ,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,KAAK,EACZ,YAAY,SAAe,EAC3B,SAAS,SAAI,GACZ,OAAO,CAAC,IAAI,CAAC;IAWV,WAAW,CACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,IAAI,CAAC;IAUhB;;;;;;;OAOG;IACG,iBAAiB,CACrB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,MAAW,GACpB,OAAO,CAAC,KAAK,EAAE,CAAC;IAgCnB;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB;IAqBzB;;OAEG;IACH,OAAO,CAAC,KAAK;IAQb;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAItD;;;;;;;;OAQG;IACG,UAAU,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;IAIpC;;;;;;;;OAQG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;CAG1D"}

package/dist/collections/PlaceTypeCollection.d.ts

@@ -0,0 +1,41 @@
+/**
+ * PlaceTypeCollection - Collection manager for PlaceType objects
+ *
+ * Provides simple lookup and creation for place types.
+ */
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { PlaceType } from '../models/PlaceType';
+export declare class PlaceTypeCollection extends SmrtCollection<PlaceType> {
+    static readonly _itemClass: typeof 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
+     */
+    getOrCreate(slug: string, name?: string): Promise<PlaceType>;
+    /**
+     * Get a place type by slug
+     *
+     * @param slug - PlaceType slug to search for
+     * @returns PlaceType instance or null if not found
+     */
+    getBySlug(slug: string): Promise<PlaceType | null>;
+    /**
+     * 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
+     */
+    initializeDefaults(): Promise<PlaceType[]>;
+}
+//# sourceMappingURL=PlaceTypeCollection.d.ts.map

package/dist/collections/PlaceTypeCollection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlaceTypeCollection.d.ts","sourceRoot":"","sources":["../../src/collections/PlaceTypeCollection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,qBAAa,mBAAoB,SAAQ,cAAc,CAAC,SAAS,CAAC;IAChE,MAAM,CAAC,QAAQ,CAAC,UAAU,mBAAa;IAEvC;;;;;;OAMG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAkBlE;;;;;OAKG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAIxD;;;;;;;;;;;;;OAaG;IACG,kBAAkB,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;CAoBjD"}