rendezvous-kit 1.21.4 → 1.21.6

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 forgesworn
+Copyright (c) 2026 TheCryptoDonkey
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,5 +1,7 @@
 # rendezvous-kit
 
+**Nostr:** [`npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2`](https://njump.me/npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2)
+
 **Find fair meeting points for N people — isochrone intersection, venue search, and fairness scoring.**
 
 [![npm](https://img.shields.io/npm/v/rendezvous-kit)](https://www.npmjs.com/package/rendezvous-kit)
@@ -92,12 +94,12 @@ for (const s of suggestions) {
 
 ## Engine Support
 
-| Engine | Isochrone | Route Matrix | Auth |
-|--------|:---------:|:------------:|------|
-| Valhalla | Yes | Yes | None (self-hosted) |
-| OpenRouteService | Yes | Yes | API key |
-| GraphHopper | Yes | Yes | API key (optional) |
-| OSRM | No | Yes | None (self-hosted) |
+| Engine | Isochrone | Route Matrix | Route | Auth |
+|--------|:---------:|:------------:|:-----:|------|
+| Valhalla | Yes | Yes | Yes | None (self-hosted) |
+| OpenRouteService | Yes | Yes | No | API key |
+| GraphHopper | Yes | Yes | No | API key (optional) |
+| OSRM | No | Yes | No | None (self-hosted) |
 
 OSRM does not support isochrone computation — use it only when you need a fast route matrix and are supplying your own intersection polygon.
 
@@ -152,14 +154,17 @@ OSRM does not support isochrone computation — use it only when you need a fast
 | `GeoJSONPolygon` | Standard GeoJSON polygon geometry |
 | `TransportMode` | `'drive' \| 'cycle' \| 'walk' \| 'public_transit'` |
 | `FairnessStrategy` | `'min_max' \| 'min_total' \| 'min_variance'` |
-| `VenueType` | `'park' \| 'cafe' \| 'restaurant' \| 'service_station' \| 'library' \| 'pub' \| 'playground' \| 'community_centre' \| string` |
-| `RoutingEngine` | Interface — `computeIsochrone` + `computeRouteMatrix` |
+| `VenueType` | `'park' \| 'cafe' \| 'restaurant' \| 'service_station' \| 'library' \| 'pub' \| 'playground' \| 'community_centre' \| 'bar' \| 'fast_food' \| 'garden' \| 'theatre' \| 'arts_centre' \| 'fitness_centre' \| 'sports_centre' \| 'escape_game' \| 'swimming_pool' \| string` |
+| `RoutingEngine` | Interface — `computeIsochrone` + `computeRouteMatrix` + `computeRoute` |
 | `Isochrone` | `{ origin, mode, timeMinutes, polygon }` |
 | `MatrixEntry` | `{ originIndex, destinationIndex, durationMinutes, distanceKm }` |
 | `RouteMatrix` | `{ origins, destinations, entries }` |
 | `Venue` | `{ name, lat, lon, venueType, osmId? }` |
-| `RendezvousOptions` | `{ participants, mode, maxTimeMinutes, venueTypes, fairness?, limit? }` |
-| `RendezvousSuggestion` | `{ venue, travelTimes, fairnessScore }` |
+| `RendezvousOptions` | `{ participants, mode, maxTimeMinutes, venueTypes, fairness?, limit?, strategy? }` |
+| `RendezvousSuggestion` | `{ venue, travelTimes, fairnessScore, metadata? }` |
+| `RouteGeometry` | `{ origin, destination, mode, durationMinutes, distanceKm, geometry, legs? }` |
+| `RouteLeg` | `{ instruction, distanceKm, durationMinutes, type?, streetNames?, ... }` |
+| `GeoJSONLineString` | `{ type: 'LineString', coordinates: number[][] }` |
 | `BBox` | `{ minLon, minLat, maxLon, maxLat }` |
 | `Coordinate` | `{ lat, lon }` |
 
@@ -194,7 +199,7 @@ If the isochrones do not overlap, `findRendezvous` returns an empty array. If no
 ## Implementing a Custom Engine
 
 ```typescript
-import type { RoutingEngine, LatLon, TransportMode, Isochrone, RouteMatrix } from 'rendezvous-kit'
+import type { RoutingEngine, LatLon, TransportMode, Isochrone, RouteMatrix, RouteGeometry } from 'rendezvous-kit'
 
 class MyEngine implements RoutingEngine {
   readonly name = 'MyEngine'
@@ -206,6 +211,10 @@ class MyEngine implements RoutingEngine {
   async computeRouteMatrix(origins: LatLon[], destinations: LatLon[], mode: TransportMode): Promise<RouteMatrix> {
     // call your API and return a RouteMatrix
   }
+
+  async computeRoute(origin: LatLon, destination: LatLon, mode: TransportMode): Promise<RouteGeometry> {
+    // call your API and return a RouteGeometry with optional turn-by-turn legs
+  }
 }
 ```
 
@@ -235,6 +244,138 @@ Run any example with `npx tsx examples/<name>.ts`.
 
 See [llms.txt](./llms.txt) for a concise API summary, or [llms-full.txt](./llms-full.txt) for the complete reference with examples.
 
+## How the Pipeline Works
+
+### Step 1: Parallel isochrone computation
+
+`findRendezvous` computes a reachability polygon for each participant in parallel.
+Every participant gets their own isochrone — a polygon representing everywhere they
+can reach within `maxTimeMinutes` using the specified transport mode:
+
+```typescript
+// Internally, all N isochrones are fetched concurrently:
+const isochrones = await Promise.all(
+  participants.map(p => engine.computeIsochrone(p, mode, maxTimeMinutes))
+)
+```
+
+This works identically for 2, 5, or 20 participants — each gets their own polygon.
+The engine does the heavy lifting; rendezvous-kit just orchestrates the parallel calls.
+
+### Step 2: N-polygon intersection
+
+All isochrone polygons are intersected left-to-right using Sutherland–Hodgman clipping.
+The result is the geographic area reachable by **every** participant within the time budget:
+
+```typescript
+import { intersectPolygonsAll } from 'rendezvous-kit/geo'
+
+// Folds left-to-right: clip polygon 2 against 1, then clip 3 against that result, etc.
+// Preserves disconnected components (e.g. two separate road corridors)
+const components = intersectPolygonsAll(isochrones.map(iso => iso.polygon))
+```
+
+If the intersection is empty (participants too far apart), `findRendezvous` returns `[]`.
+
+### Step 3: Venue search and scoring
+
+Venues are searched within the intersection zone via Overpass API, then each venue is
+scored using the chosen fairness strategy:
+
+```typescript
+const suggestions = await findRendezvous(engine, {
+  participants: [alice, bob, carol],
+  mode: 'drive',
+  maxTimeMinutes: 90,
+  venueTypes: ['cafe', 'restaurant'],
+  fairness: 'min_max',   // minimise the worst individual travel time
+  limit: 5,
+})
+// Each suggestion has: venue, travelTimes (per participant), fairnessScore
+```
+
+### When isochrones don't overlap
+
+If the isochrones don't intersect, `findRendezvous` returns an empty array. Options:
+
+1. **Increase `maxTimeMinutes`** — expand the reachability polygons
+2. **Switch transport mode** — `'drive'` covers more ground than `'walk'`
+3. **Use the `hull` strategy** — for nearby participants, the library automatically uses
+   a convex hull of participant positions as the search region instead of isochrones.
+   This always produces results because it searches the area *between* participants.
+
+If the intersection exists but contains no matching venues, the library falls back to
+a synthetic "Meeting point" at the area-weighted centroid of the intersection.
+
+## Switching Routing Engines
+
+OSRM does not support isochrone computation. If you're using OSRM and need the full
+pipeline, swap to an isochrone-capable engine:
+
+```typescript
+// Before: OSRM (route matrix only — no isochrones)
+import { OsrmEngine } from 'rendezvous-kit/engines/osrm'
+const engine = new OsrmEngine({ baseUrl: 'http://localhost:5000' })
+
+// After: Valhalla (self-hosted, free, full isochrone support)
+import { ValhallaEngine } from 'rendezvous-kit/engines/valhalla'
+const engine = new ValhallaEngine({ baseUrl: 'http://localhost:8002' })
+
+// Or: OpenRouteService (hosted API, requires free API key)
+import { OpenRouteServiceEngine } from 'rendezvous-kit/engines/openrouteservice'
+const engine = new OpenRouteServiceEngine({
+  apiKey: process.env.ORS_API_KEY!,
+  baseUrl: 'https://api.openrouteservice.org', // default
+})
+
+// Or: GraphHopper (self-hosted or hosted, API key optional for self-hosted)
+import { GraphHopperEngine } from 'rendezvous-kit/engines/graphhopper'
+const engine = new GraphHopperEngine({
+  baseUrl: 'http://localhost:8989',
+  apiKey: process.env.GRAPHHOPPER_KEY, // optional for self-hosted
+})
+
+// All engines implement the same RoutingEngine interface.
+// The rest of your code stays identical:
+const suggestions = await findRendezvous(engine, { participants, mode, ... })
+```
+
+For self-hosting guides (Docker one-liners for Valhalla, OSRM, GraphHopper), see
+[Self-Hosting a Routing Engine](./docs/self-hosting-a-routing-engine.md).
+
+## Architecture
+
+rendezvous-kit's pipeline combines two kinds of spatial operations:
+
+**Routing engine operations** (external): isochrone computation, route matrix, and
+route geometry. These call your chosen engine's HTTP API for real road-network
+calculations.
+
+**Local geometry operations** (pure TypeScript, no dependencies): polygon intersection
+(Sutherland–Hodgman), area calculation (shoelace), centroid computation, bounding boxes,
+and convex hull (via `geohash-kit/coverage`). These run entirely in-process with no
+network calls.
+
+The only external dependency is `geohash-kit`, which provides the `convexHull` function
+used by the hull-strategy fast path for nearby participants. All other polygon operations
+(intersection, clipping, triangulation, area) are implemented in `rendezvous-kit/geo`.
+
+```
+Participants ──→ Engine.computeIsochrone() ──→ Polygon[]
+                                                  │
+                                    intersectPolygonsAll()  ← local geometry
+                                                  │
+                                          Intersection zone
+                                                  │
+                                    searchVenues() via Overpass API
+                                                  │
+                              Engine.computeRouteMatrix() ──→ travel times
+                                                  │
+                                         scoreVenues()  ← local fairness calc
+                                                  │
+                                        Ranked suggestions
+```
+
 ## Troubleshooting
 
 **`findRendezvous` returns an empty array**
@@ -252,6 +393,23 @@ Check that your engine base URL is correct and the service is running. For ORS,
 **OSRM: `Error: OSRM does not support isochrone computation`**
 OSRM cannot generate isochrones. Use Valhalla, OpenRouteService, or GraphHopper instead. OSRM is supported only for route matrix computation.
 
+## Part of the ForgeSworn Toolkit
+
+[ForgeSworn](https://forgesworn.dev) builds open-source cryptographic identity, payments, and coordination tools for Nostr.
+
+| Library | What it does |
+|---------|-------------|
+| [nsec-tree](https://github.com/forgesworn/nsec-tree) | Deterministic sub-identity derivation |
+| [ring-sig](https://github.com/forgesworn/ring-sig) | SAG/LSAG ring signatures on secp256k1 |
+| [range-proof](https://github.com/forgesworn/range-proof) | Pedersen commitment range proofs |
+| [canary-kit](https://github.com/forgesworn/canary-kit) | Coercion-resistant spoken verification |
+| [spoken-token](https://github.com/forgesworn/spoken-token) | Human-speakable verification tokens |
+| [toll-booth](https://github.com/forgesworn/toll-booth) | L402 payment middleware |
+| [geohash-kit](https://github.com/forgesworn/geohash-kit) | Geohash toolkit with polygon coverage |
+| [nostr-attestations](https://github.com/forgesworn/nostr-attestations) | NIP-VA verifiable attestations |
+| [dominion](https://github.com/forgesworn/dominion) | Epoch-based encrypted access control |
+| [nostr-veil](https://github.com/forgesworn/nostr-veil) | Privacy-preserving Web of Trust |
+
 ## Licence
 
 [MIT](https://github.com/forgesworn/rendezvous-kit/blob/main/LICENSE)

package/llms-full.txt

@@ -63,6 +63,15 @@ type VenueType =
   | 'pub'
   | 'playground'
   | 'community_centre'
+  | 'bar'
+  | 'fast_food'
+  | 'garden'
+  | 'theatre'
+  | 'arts_centre'
+  | 'fitness_centre'
+  | 'sports_centre'
+  | 'escape_game'
+  | 'swimming_pool'
   | string
 
 /** Result of an isochrone computation. */
@@ -97,6 +106,43 @@ interface Venue {
   osmId?: string  // e.g. 'node/123456'
 }
 
+/** GeoJSON LineString geometry. */
+interface GeoJSONLineString {
+  type: 'LineString'
+  coordinates: number[][]
+}
+
+/** A single manoeuvre in a route. */
+interface RouteLeg {
+  instruction: string
+  distanceKm: number
+  durationMinutes: number
+  type?: number              // Valhalla manoeuvre type (0-38)
+  streetNames?: string[]
+  beginStreetNames?: string[]
+  verbalInstruction?: string
+  toll?: boolean
+  highway?: boolean
+  ferry?: boolean
+  rough?: boolean
+  gate?: boolean
+  bearingBefore?: number
+  bearingAfter?: number
+  beginShapeIndex?: number
+  endShapeIndex?: number
+}
+
+/** Result of a single route computation. */
+interface RouteGeometry {
+  origin: LatLon
+  destination: LatLon
+  mode: TransportMode
+  durationMinutes: number
+  distanceKm: number
+  geometry: GeoJSONLineString
+  legs?: RouteLeg[]
+}
+
 /** Options for rendezvous calculation. */
 interface RendezvousOptions {
   participants: LatLon[]       // at least 2 required
@@ -105,6 +151,7 @@ interface RendezvousOptions {
   venueTypes: VenueType[]
   fairness?: FairnessStrategy  // default: 'min_max'
   limit?: number               // max suggestions to return, default: 5
+  strategy?: 'auto' | 'hull' | 'isochrone'  // pipeline strategy, default: 'auto'
 }
 
 /** A ranked rendezvous suggestion. */
@@ -112,6 +159,7 @@ interface RendezvousSuggestion {
   venue: Venue
   travelTimes: Record<string, number>  // keyed by participant label or 'participant_N'
   fairnessScore: number                // lower is better
+  metadata?: { strategy: 'hull' | 'isochrone' }  // which pipeline was used
 }
 
 /** Engine-agnostic routing interface. Implement this to add a custom engine. */
@@ -119,6 +167,7 @@ interface RoutingEngine {
   readonly name: string
   computeIsochrone(origin: LatLon, mode: TransportMode, timeMinutes: number): Promise<Isochrone>
   computeRouteMatrix(origins: LatLon[], destinations: LatLon[], mode: TransportMode): Promise<RouteMatrix>
+  computeRoute(origin: LatLon, destination: LatLon, mode: TransportMode): Promise<RouteGeometry>
 }
 
 /** Bounding box (from rendezvous-kit/geo). */
@@ -413,6 +462,15 @@ Built-in `VenueType` to Overpass tag mapping:
 | `pub` | `amenity=pub` |
 | `playground` | `leisure=playground` |
 | `community_centre` | `amenity=community_centre` |
+| `bar` | `amenity=bar` |
+| `fast_food` | `amenity=fast_food` |
+| `garden` | `leisure=garden` |
+| `theatre` | `amenity=theatre` |
+| `arts_centre` | `amenity=arts_centre` |
+| `fitness_centre` | `leisure=fitness_centre` |
+| `sports_centre` | `leisure=sports_centre` |
+| `escape_game` | `leisure=escape_game` |
+| `swimming_pool` | `leisure=swimming_pool` |
 
 Unknown strings are passed through as `amenity=<value>`.
 
@@ -421,7 +479,7 @@ Unknown strings are passed through as `amenity=<value>`.
 ## Implementing a Custom Engine
 
 ```typescript
-import type { RoutingEngine, LatLon, TransportMode, Isochrone, RouteMatrix } from 'rendezvous-kit'
+import type { RoutingEngine, LatLon, TransportMode, Isochrone, RouteMatrix, RouteGeometry } from 'rendezvous-kit'
 
 class MyRoutingEngine implements RoutingEngine {
   readonly name = 'MyEngine'
@@ -454,6 +512,27 @@ class MyRoutingEngine implements RoutingEngine {
     }
     return { origins, destinations, entries }
   }
+
+  async computeRoute(
+    origin: LatLon,
+    destination: LatLon,
+    mode: TransportMode,
+  ): Promise<RouteGeometry> {
+    const raw = await myApi.getRoute(origin, destination, mode)
+    return {
+      origin,
+      destination,
+      mode,
+      durationMinutes: raw.seconds / 60,
+      distanceKm: raw.metres / 1000,
+      geometry: { type: 'LineString', coordinates: raw.polyline },
+      legs: raw.steps.map((s: any) => ({
+        instruction: s.text,
+        distanceKm: s.metres / 1000,
+        durationMinutes: s.seconds / 60,
+      })),
+    }
+  }
 }
 
 // Use it with findRendezvous
@@ -464,12 +543,12 @@ const suggestions = await findRendezvous(new MyRoutingEngine(), options)
 
 ## Engine Comparison
 
-| Engine | Isochrone | Matrix | Auth | Notes |
-|--------|:---------:|:------:|------|-------|
-| Valhalla | Yes | Yes | None | Best self-hosted option; supports public transit |
-| OpenRouteService | Yes | Yes | API key | Free tier available; no public transit |
-| GraphHopper | Yes | Yes | Optional | API key only for cloud; optional self-hosted |
-| OSRM | No | Yes | None | Fastest matrix; no isochrone support |
+| Engine | Isochrone | Matrix | Route | Auth | Notes |
+|--------|:---------:|:------:|:-----:|------|-------|
+| Valhalla | Yes | Yes | Yes | None | Best self-hosted option; supports public transit |
+| OpenRouteService | Yes | Yes | No | API key | Free tier available; no public transit |
+| GraphHopper | Yes | Yes | No | Optional | API key only for cloud; optional self-hosted |
+| OSRM | No | Yes | No | None | Fastest matrix; no isochrone support |
 
 ---
 

package/llms.txt

@@ -52,10 +52,13 @@ Pure-TypeScript polygon geometry.
 - GeoJSONPolygon: { type: 'Polygon', coordinates: number[][][] }
 - TransportMode: 'drive' | 'cycle' | 'walk' | 'public_transit'
 - FairnessStrategy: 'min_max' | 'min_total' | 'min_variance'
-- VenueType: 'park' | 'cafe' | 'restaurant' | 'service_station' | 'library' | 'pub' | 'playground' | 'community_centre' | string
-- RendezvousOptions: { participants, mode, maxTimeMinutes, venueTypes, fairness?, limit? }
-- RendezvousSuggestion: { venue, travelTimes: Record<string, number>, fairnessScore }
-- RoutingEngine: interface { name, computeIsochrone, computeRouteMatrix }
+- VenueType: 'park' | 'cafe' | 'restaurant' | 'service_station' | 'library' | 'pub' | 'playground' | 'community_centre' | 'bar' | 'fast_food' | 'garden' | 'theatre' | 'arts_centre' | 'fitness_centre' | 'sports_centre' | 'escape_game' | 'swimming_pool' | string
+- RendezvousOptions: { participants, mode, maxTimeMinutes, venueTypes, fairness?, limit?, strategy? }
+- RendezvousSuggestion: { venue, travelTimes: Record<string, number>, fairnessScore, metadata? }
+- RoutingEngine: interface { name, computeIsochrone, computeRouteMatrix, computeRoute }
+- RouteGeometry: { origin, destination, mode, durationMinutes, distanceKm, geometry: GeoJSONLineString, legs?: RouteLeg[] }
+- RouteLeg: { instruction, distanceKm, durationMinutes, type?, streetNames?, verbalInstruction?, ... }
+- GeoJSONLineString: { type: 'LineString', coordinates: number[][] }
 
 ## Fairness Strategies
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rendezvous-kit",
-  "version": "1.21.4",
+  "version": "1.21.6",
   "type": "module",
   "description": "Find fair meeting points for N people — isochrone intersection, venue search, and fairness scoring.",
   "main": "./dist/index.js",
@@ -85,6 +85,6 @@
   "homepage": "https://github.com/forgesworn/rendezvous-kit",
   "funding": {
     "type": "lightning",
-    "url": "https://strike.me/thedonkey"
+    "url": "lightning:thedonkey@strike.me"
   }
 }