@happyvertical/smrt-places 0.30.0

package/dist/index.d.ts

@@ -0,0 +1,606 @@
+import { Asset } from '@happyvertical/smrt-assets';
+import { HierarchyView } from '@happyvertical/smrt-core';
+import { Location } from '@happyvertical/geo';
+import { SmrtCollection } from '@happyvertical/smrt-core';
+import { SmrtHierarchical } from '@happyvertical/smrt-core';
+import { SmrtJunction } from '@happyvertical/smrt-core';
+import { SmrtObject } from '@happyvertical/smrt-core';
+import { SmrtObjectOptions } from '@happyvertical/smrt-core';
+
+/**
+ * Check if two coordinates are within a threshold distance
+ *
+ * @param lat1 - First latitude
+ * @param lng1 - First longitude
+ * @param lat2 - Second latitude
+ * @param lng2 - Second longitude
+ * @param thresholdKm - Distance threshold in kilometers
+ * @returns True if coordinates are within threshold
+ */
+export declare function areCoordinatesNear(lat1: number, lng1: number, lat2: number, lng2: number, thresholdKm?: number): boolean;
+
+/**
+ * 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
+ */
+export declare function calculateDistance(lat1: number, lng1: number, lat2: number, lng2: number): number;
+
+/**
+ * Options for `PlaceCollection.discoverNearby`. Mirrors the inputs to
+ * `@happyvertical/geo`'s `findPoisNear` plus a couple of persistence knobs
+ * (PlaceType override, parent linkage) to match `lookupOrCreate`'s shape.
+ */
+export declare interface DiscoverNearbyOptions {
+    /** Which geo provider to use. Defaults to openstreetmap. */
+    geoProvider?: 'google' | 'openstreetmap';
+    /**
+     * POI category filter, forwarded to the provider. See
+     * `@happyvertical/geo`'s `PoiSearchOptions.types` for provider-specific
+     * interpretation.
+     */
+    types?: string[];
+    /** Free-text keyword filter (provider-dependent; Google only). */
+    keyword?: string;
+    /** Max results per provider call. Default 20. */
+    limit?: number;
+    /** Preferred language for place names (Google only). */
+    language?: string;
+    /** Override the PlaceType slug assigned to created rows. */
+    typeSlug?: string;
+    /** Set parent place on created rows. */
+    parentId?: string | null;
+}
+
+/**
+ * Format coordinates as string
+ *
+ * @param latitude - Latitude value
+ * @param longitude - Longitude value
+ * @param precision - Number of decimal places (default: 6)
+ * @returns Formatted coordinate string
+ */
+export declare function formatCoordinates(latitude: number, longitude: number, precision?: number): string;
+
+/**
+ * Generate a display name from address components
+ *
+ * @param components - Address components
+ * @returns Formatted display name
+ */
+export declare function generateDisplayName(components: Partial<GeoData>): string;
+
+/**
+ * Geographic data structure
+ * All fields optional to support both real-world and abstract places
+ */
+export declare interface GeoData {
+    latitude: number | null;
+    longitude: number | null;
+    streetNumber?: string;
+    streetName?: string;
+    city?: string;
+    region?: string;
+    country?: string;
+    postalCode?: string;
+    countryCode?: string;
+    timezone?: string;
+}
+
+/**
+ * Convert Location from @happyvertical/geo to GeoData
+ *
+ * @param location - Location from geocoding
+ * @returns GeoData object
+ */
+export declare function locationToGeoData(location: Location): GeoData;
+
+/**
+ * Options for lookupOrCreate method
+ */
+export declare interface LookupOrCreateOptions {
+    /**
+     * Which geo provider to use for lookups
+     */
+    geoProvider?: 'google' | 'openstreetmap';
+    /**
+     * Force a specific place type
+     */
+    typeSlug?: string;
+    /**
+     * Set parent place if known
+     */
+    parentId?: string | null;
+    /**
+     * Whether to create if not found (default: true)
+     */
+    createIfNotFound?: boolean;
+    /**
+     * Coordinates for reverse geocoding
+     */
+    coords?: {
+        lat: number;
+        lng: number;
+    };
+}
+
+/**
+ * Map Location type from @happyvertical/geo to PlaceType slug
+ *
+ * @param locationType - Location type from geocoding provider
+ * @returns PlaceType slug
+ */
+export declare function mapLocationTypeToPlaceType(locationType: string): string;
+
+/**
+ * Normalize address components by trimming and removing empty values
+ *
+ * @param components - Address components
+ * @returns Normalized components
+ */
+export declare function normalizeAddressComponents(components: Partial<GeoData>): Partial<GeoData>;
+
+/**
+ * Parse coordinate string to lat/lng
+ *
+ * Supports formats:
+ * - "lat, lng"
+ * - "lat,lng"
+ * - "lat lng"
+ *
+ * @param coordString - Coordinate string
+ * @returns Object with lat and lng, or null if invalid
+ */
+export declare function parseCoordinates(coordString: string): {
+    lat: number;
+    lng: number;
+} | null;
+
+export declare class Place extends SmrtHierarchical {
+    tenantId: string | null;
+    typeId: string;
+    name: string;
+    description: string;
+    latitude: number | null;
+    longitude: number | null;
+    streetNumber: string;
+    streetName: string;
+    city: string;
+    region: string;
+    country: string;
+    postalCode: string;
+    countryCode: string;
+    timezone: string;
+    externalId: string;
+    source: string;
+    metadata: string;
+    createdAt: Date;
+    updatedAt: Date;
+    constructor(options?: PlaceOptions);
+    /**
+     * Get geographic data for this place
+     *
+     * @returns GeoData object with all geo fields
+     */
+    getGeoData(): GeoData;
+    /**
+     * Check if this place has geographic coordinates
+     *
+     * @returns True if latitude and longitude are set
+     */
+    hasCoordinates(): boolean;
+    /**
+     * Get metadata as parsed object
+     *
+     * @returns Parsed metadata object or empty object if no metadata
+     */
+    getMetadata(): Record<string, any>;
+    /**
+     * Set metadata from object
+     *
+     * @param data - Metadata object to store
+     */
+    setMetadata(data: Record<string, any>): void;
+    /**
+     * Update metadata by merging with existing values
+     *
+     * @param updates - Partial metadata to merge
+     */
+    updateMetadata(updates: Record<string, any>): void;
+    /**
+     * Get the place type
+     *
+     * @returns PlaceType instance or null if not found
+     */
+    getType(): Promise<any>;
+    private getPlaceAssetCollection;
+    getAssets(relationship?: string): Promise<Asset[]>;
+    addAsset(asset: Asset, relationship?: string, sortOrder?: number): Promise<void>;
+    removeAsset(assetId: string, relationship?: string): Promise<void>;
+}
+
+export declare class PlaceAsset extends SmrtObject {
+    tenantId: string | null;
+    placeId: string;
+    assetId: string;
+    relationship: string;
+    sortOrder: number;
+    constructor(options?: PlaceAssetOptions);
+}
+
+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>;
+}
+
+export declare interface PlaceAssetOptions extends SmrtObjectOptions {
+    placeId?: string;
+    assetId?: string;
+    relationship?: string;
+    sortOrder?: number;
+    tenantId?: string | null;
+}
+
+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<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)
+     *
+     * @returns Array of global places
+     */
+    findGlobal(): Promise<Place[]>;
+    /**
+     * Find places for a tenant including global places
+     *
+     * @param tenantId - The tenant ID to include
+     * @returns Array of tenant-specific and global places
+     */
+    findWithGlobals(tenantId: string): Promise<Place[]>;
+}
+
+/**
+ * Place hierarchy structure
+ */
+export declare interface PlaceHierarchy {
+    ancestors: any[];
+    current: any;
+    descendants: any[];
+}
+
+/**
+ * Options for creating/updating a Place
+ */
+export declare interface PlaceOptions extends SmrtObjectOptions {
+    id?: string;
+    tenantId?: string | null;
+    typeId?: string;
+    parentId?: string | null;
+    name?: string;
+    description?: string;
+    latitude?: number | null;
+    longitude?: number | null;
+    streetNumber?: string;
+    streetName?: string;
+    city?: string;
+    region?: string;
+    country?: string;
+    postalCode?: string;
+    countryCode?: string;
+    timezone?: string;
+    externalId?: string;
+    source?: string;
+    metadata?: Record<string, any> | string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+
+export declare class PlaceType extends SmrtObject {
+    name: string;
+    description?: string;
+    createdAt: Date;
+    updatedAt: Date;
+    constructor(options?: PlaceTypeOptions);
+    /**
+     * Convenience method for slug-based lookup
+     *
+     * @param slug - The slug to search for
+     * @returns PlaceType instance or null if not found
+     */
+    static getBySlug(_slug: string): Promise<PlaceType | null>;
+}
+
+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[]>;
+}
+
+/**
+ * Options for creating/updating a PlaceType
+ */
+export declare interface PlaceTypeOptions extends SmrtObjectOptions {
+    id?: string;
+    slug?: string;
+    name?: string;
+    description?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+
+/**
+ * Options for `PlaceCollection.resolveTrackPlaces`. Extends
+ * `DiscoverNearbyOptions` with per-track knobs that control how the track
+ * is bucketed + throttled before hitting the geo provider.
+ */
+export declare interface ResolveTrackPlacesOptions extends DiscoverNearbyOptions {
+    /**
+     * Per-point POI search radius in meters. Default 50.
+     */
+    radiusMeters?: number;
+    /**
+     * Collapse points within this distance (m) into a single bucket so we
+     * don't re-query the same ~50m area dozens of times for a slow drive-by.
+     * Default 50.
+     */
+    bucketMeters?: number;
+    /**
+     * Minimum delay between provider requests. Default 1100ms — safely above
+     * OSM's 1 req/sec community limit. Google can usually handle faster; set
+     * to 100ms or less for paid tiers.
+     */
+    throttleMs?: number;
+}
+
+/**
+ * Result of `PlaceCollection.resolveTrackPlaces`. Tracks are typically
+ * long-running operations so the return payload includes counters that let
+ * callers surface progress or estimate cost without re-walking.
+ */
+export declare interface TrackPlacesResult {
+    /** De-duplicated Place rows touched during resolution. */
+    places: any[];
+    /** Number of provider requests issued. */
+    requestCount: number;
+    /** Number of bucketed points that reused existing Place rows. */
+    cacheHitCount: number;
+    /** Number of distinct geographic buckets walked. */
+    bucketCount: number;
+}
+
+/**
+ * A single point along a track. Matches the `{ lat, lng }` convention used
+ * by `LookupOrCreateOptions.coords` so callers don't have to shuffle shapes.
+ */
+export declare interface TrackPoint {
+    lat: number;
+    lng: number;
+}
+
+/**
+ * Validate geographic coordinates
+ *
+ * @param latitude - Latitude value
+ * @param longitude - Longitude value
+ * @returns Object with valid flag and optional error message
+ */
+export declare function validateCoordinates(latitude: number, longitude: number): {
+    valid: boolean;
+    error?: string;
+};
+
+export { }