@happyvertical/smrt-places 0.57.36 → 0.57.37

package/dist/smrt-knowledge.json

@@ -3,13 +3,13 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-places",
-  "packageVersion": "0.57.36",
+  "packageVersion": "0.57.37",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "d70331d1b4596cf6e9f7b2d2611d0ff8f277dfd63b5aaae7d766d50cfbe413a1",
-    "packageJson": "a1f801ab278eed4f208cd899828d881386ac0fe66073a9c16f212236da5ed75c",
-    "agents": "1f12a465f3ef103ac0ba27bcec1ec2b982fd0f5e8a63b9a42738f2c79ecebe49"
+    "manifest": "d7701265ab3b7339a8c9f52ca524d49abc195c004f98ec49bde076f5bc62bd28",
+    "packageJson": "49012c674d84ea10fde9b440950d1069e82b0887c36a56663c3b716e7521a9cd",
+    "agents": "8b7e9c23fd1311b3d04afe693969c1caaaa5d166e436f48e70c3504efbbadce9"
   },
   "exports": [
     ".",
@@ -695,91 +695,106 @@
           "type": "foreignKey",
           "required": false,
           "related": "PlaceType",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "What kind of place this is, such as a building, a room or a storage zone."
         },
         {
           "name": "name",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "What the place is called, such as \"Main warehouse\" or \"Aisle 4\"."
         },
         {
           "name": "description",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "A few words about the place and what happens there."
         },
         {
           "name": "latitude",
           "type": "decimal",
           "required": false,
-          "columnType": "REAL"
+          "columnType": "REAL",
+          "description": "How far north or south the place is on a map. Leave empty for a place that is not on a map."
         },
         {
           "name": "longitude",
           "type": "decimal",
           "required": false,
-          "columnType": "REAL"
+          "columnType": "REAL",
+          "description": "How far east or west the place is on a map. Leave empty for a place that is not on a map."
         },
         {
           "name": "streetNumber",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The number of the building on its street."
         },
         {
           "name": "streetName",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The name of the street the place is on."
         },
         {
           "name": "city",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The town or city the place is in."
         },
         {
           "name": "region",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The state, province or region the place is in."
         },
         {
           "name": "country",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The country the place is in."
         },
         {
           "name": "postalCode",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The postal or zip code of the address."
         },
         {
           "name": "countryCode",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The short two-letter code for the country, such as CA or US."
         },
         {
           "name": "timezone",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The time zone the place keeps, such as America/Toronto."
         },
         {
           "name": "externalId",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "The reference the map provider uses for this place, filled in when the app looks it up."
         },
         {
           "name": "source",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "Which map provider the place was looked up from, if any."
         },
         {
           "name": "metadata",
@@ -1384,13 +1399,15 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The name of the kind of place, such as \"Building\", \"Room\" or \"Zone\"."
         },
         {
           "name": "description",
           "type": "text",
           "required": false,
-          "columnType": "TEXT"
+          "columnType": "TEXT",
+          "description": "A few words about when to use this kind of place."
         },
         {
           "name": "createdAt",
@@ -1936,7 +1953,166 @@
     "polymorphicAssociations": 0,
     "uuidColumns": 18
   },
-  "agentDoc": "# @happyvertical/smrt-places\n\nHierarchical geographic database with organic growth via geocoding integration.\n\n## Models\n\n- **Place** (STI): hierarchical via `parentId`. Optional geo fields (all nullable — supports abstract places like game zones). `externalId`/`source` from geocoder. Metadata JSON.\n- **PlaceAsset**: dedicated owned-asset join in `place_assets` with `relationship` and `sortOrder`.\n- **PlaceType**: slug-based classification (country, city, building, zone, room, region).\n\n## Key Collection Methods\n\n| Method | Purpose |\n|--------|---------|\n| `lookupOrCreate(query)` | DB first → geocode if not found → create. Organic growth pattern. |\n| `findByCoordinates(lat, lng, threshold)` | Default 0.0001° ≈ 11m tolerance at equator |\n| `searchByProximity(lat, lng, radiusKm)` | Haversine distance, sorted by proximity |\n| `findWithGlobals(tenantId)` | Tenant + global (tenantId=null) places |\n| `getRootPlaces()`, `getByType(slug)` | Hierarchy + type queries |\n| `getAssets()` / `addAsset()` / `removeAsset()` | Owned asset helpers on both `Place` and `PlaceCollection`, backed by `place_assets` |\n\nHierarchy traversal: `getParent()`, `getChildren()`, `getAncestors()`, `getDescendants()`, `getHierarchy()`.\n\n## Gotchas\n\n- **Geo providers**: Google Maps needs `GOOGLE_MAPS_API_KEY`; OpenStreetMap is default\n- **Abstract places allowed**: lat/lng nullable — supports non-geographic locations\n- **Coordinate tolerance varies by latitude**: 0.0001° ≈ 11m at equator, less at poles\n- **Optional tenancy** with nullable tenantId\n",
+  "agentDoc": "# @happyvertical/smrt-places\n\nHierarchical geographic database with organic growth via geocoding integration.\n\n## Models\n\n- **Place** (STI): hierarchical via `parentId`. Optional geo fields (all nullable — supports abstract places like game zones). `externalId`/`source` from geocoder. Metadata JSON.\n- **PlaceAsset**: dedicated owned-asset join in `place_assets` with `relationship` and `sortOrder`.\n- **PlaceType**: slug-based classification (country, city, building, zone, room, region).\n- **Recipe `places.locations`** (`src/recipes.ts`, help in `src/locations.recipe.md`): lists places and place types for the planner and other catalog hosts; `PlaceAsset` is closed and stays out. Fields it shows carry `@field({ description })` in plain words; `parentId` (inherited) is described by the recipe's `options` help. Keep both when editing the models.\n\n## Key Collection Methods\n\n| Method | Purpose |\n|--------|---------|\n| `lookupOrCreate(query)` | DB first → geocode if not found → create. Organic growth pattern. |\n| `findByCoordinates(lat, lng, threshold)` | Default 0.0001° ≈ 11m tolerance at equator |\n| `searchByProximity(lat, lng, radiusKm)` | Haversine distance, sorted by proximity |\n| `findWithGlobals(tenantId)` | Tenant + global (tenantId=null) places |\n| `getRootPlaces()`, `getByType(slug)` | Hierarchy + type queries |\n| `getAssets()` / `addAsset()` / `removeAsset()` | Owned asset helpers on both `Place` and `PlaceCollection`, backed by `place_assets` |\n\nHierarchy traversal: `getParent()`, `getChildren()`, `getAncestors()`, `getDescendants()`, `getHierarchy()`.\n\n## Gotchas\n\n- **Geo providers**: Google Maps needs `GOOGLE_MAPS_API_KEY`; OpenStreetMap is default\n- **Abstract places allowed**: lat/lng nullable — supports non-geographic locations\n- **Coordinate tolerance varies by latitude**: 0.0001° ≈ 11m at equator, less at poles\n- **Optional tenancy** with nullable tenantId\n",
+  "recipes": [
+    {
+      "id": "places.locations",
+      "className": "PlacesLocationsRecipe",
+      "label": "Places",
+      "summary": "Keep a list of the places your work happens, such as sites, buildings, rooms and storage zones, one inside another.",
+      "synonyms": [
+        "places",
+        "locations",
+        "sites",
+        "buildings",
+        "rooms",
+        "addresses",
+        "warehouses"
+      ],
+      "models": [
+        "@happyvertical/smrt-places:Place",
+        "@happyvertical/smrt-places:PlaceType"
+      ],
+      "nav": [
+        {
+          "label": "Places",
+          "model": "@happyvertical/smrt-places:Place",
+          "icon": "home",
+          "description": "Every site, building, room and zone, with its address and what it is inside.",
+          "noun": "place"
+        },
+        {
+          "label": "Place types",
+          "model": "@happyvertical/smrt-places:PlaceType",
+          "icon": "tag",
+          "description": "The kinds of place you keep, such as building or room.",
+          "noun": "place type"
+        }
+      ],
+      "requires": [],
+      "section": {
+        "id": "places",
+        "label": "Locations",
+        "icon": "home",
+        "description": "The places your work happens."
+      },
+      "options": {
+        "@happyvertical/smrt-places:Place": {
+          "fields": {
+            "name": {
+              "order": 1
+            },
+            "typeId": {
+              "label": "Type",
+              "order": 2
+            },
+            "parentId": {
+              "label": "Inside",
+              "help": "The larger place this one is part of, such as the building a room is in.",
+              "order": 3
+            },
+            "description": {
+              "order": 4
+            },
+            "streetNumber": {
+              "label": "Street number",
+              "order": 5
+            },
+            "streetName": {
+              "label": "Street name",
+              "order": 6
+            },
+            "city": {
+              "order": 7
+            },
+            "region": {
+              "order": 8
+            },
+            "country": {
+              "order": 9
+            },
+            "postalCode": {
+              "label": "Postal code",
+              "order": 10
+            },
+            "latitude": {
+              "visibility": "advanced"
+            },
+            "longitude": {
+              "visibility": "advanced"
+            },
+            "countryCode": {
+              "label": "Country code",
+              "visibility": "advanced"
+            },
+            "timezone": {
+              "label": "Time zone",
+              "visibility": "advanced"
+            },
+            "externalId": {
+              "label": "Map reference",
+              "visibility": "advanced"
+            },
+            "source": {
+              "label": "Map provider",
+              "visibility": "advanced"
+            },
+            "metadata": {
+              "visibility": "hidden"
+            },
+            "tenantId": {
+              "visibility": "hidden"
+            },
+            "createdAt": {
+              "visibility": "hidden"
+            },
+            "updatedAt": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-places:PlaceType": {
+          "fields": {
+            "name": {
+              "order": 1
+            },
+            "description": {
+              "order": 2
+            },
+            "createdAt": {
+              "visibility": "hidden"
+            },
+            "updatedAt": {
+              "visibility": "hidden"
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nPlaces is where you keep the sites, buildings, rooms and storage zones your\nwork happens in. Each place has a name, a type and, when it is somewhere real,\nan address. A place can sit inside a larger one, so a room belongs to a\nbuilding and a shelf to a room, and you can follow that chain either way. A\nplace does not have to be on a map: a storage zone or a work area with no\naddress is fine.\n\n## Tasks\n\n### Add a place\n\n1. Open the list of places and choose **New**.\n2. Type the **{field:Place.name}**, for example \"Main warehouse\".\n3. Pick its **{field:Place.typeId}**, such as building or room. Add a type first if the one you need is missing.\n4. Fill in the address: the **{field:Place.streetNumber}**, **{field:Place.streetName}**, **{field:Place.city}**, **{field:Place.region}**, **{field:Place.country}** and **{field:Place.postalCode}**. Leave these empty for a place that is not on a map.\n5. Save. When your app searches a map for a place, it can add the place for you with the address filled in from the map provider.\n\n### Put a place inside another\n\n1. Open the place and choose to edit it.\n2. In **{field:Place.parentId}**, pick the larger place it belongs to, such as the building a room is in.\n3. Save. The place now shows up under the one you chose.\n\n### Change or remove a place\n\n1. Open the place and choose to edit it.\n2. Change the **{field:Place.name}**, **{field:Place.description}** or address, then save.\n3. To remove a place you no longer use, open it and choose to delete it. Move anything inside it first.\n\n### Add a place type\n\n1. Open the list of place types and choose **New**.\n2. Type the **{field:PlaceType.name}**, for example \"Room\".\n3. Add a **{field:PlaceType.description}** so others know when to use it.\n4. Save. The type can now be picked when you add a place.\n",
+        "fieldRefs": [
+          "Place.city",
+          "Place.country",
+          "Place.description",
+          "Place.name",
+          "Place.parentId",
+          "Place.postalCode",
+          "Place.region",
+          "Place.streetName",
+          "Place.streetNumber",
+          "Place.typeId",
+          "PlaceType.description",
+          "PlaceType.name"
+        ]
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package does not build for a browser: geo -> cache -> redis, node:zlib; url-signature node:crypto; and its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3624, #3627)."
+        ]
+      }
+    }
+  ],
   "browser": {
     "status": "server-only",
     "issues": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-places",
-  "version": "0.57.36",
+  "version": "0.57.37",
   "description": "Hierarchical place management with geo integration and SMRT framework support",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,19 +23,19 @@
     "./manifest.json": "./dist/manifest.json"
   },
   "dependencies": {
-    "@happyvertical/ai": "^0.109.0",
-    "@happyvertical/cache": "^0.109.0",
-    "@happyvertical/files": "^0.109.0",
-    "@happyvertical/geo": "^0.109.0",
-    "@happyvertical/logger": "^0.109.0",
-    "@happyvertical/smrt-assets": "0.57.36",
-    "@happyvertical/smrt-core": "0.57.36",
-    "@happyvertical/smrt-tenancy": "0.57.36",
-    "@happyvertical/sql": "^0.109.0",
-    "@happyvertical/utils": "^0.109.0"
+    "@happyvertical/ai": "^0.110.0",
+    "@happyvertical/cache": "^0.110.0",
+    "@happyvertical/files": "^0.110.0",
+    "@happyvertical/geo": "^0.110.0",
+    "@happyvertical/logger": "^0.110.0",
+    "@happyvertical/smrt-assets": "0.57.37",
+    "@happyvertical/smrt-core": "0.57.37",
+    "@happyvertical/smrt-tenancy": "0.57.37",
+    "@happyvertical/sql": "^0.110.0",
+    "@happyvertical/utils": "^0.110.0"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.57.36",
+    "@happyvertical/smrt-vitest": "0.57.37",
     "@types/node": "24.13.6",
     "typescript": "6.0.3",
     "vite": "8.1.6",