geohash-kit 1.0.0

package/dist/nostr.d.ts

@@ -0,0 +1,31 @@
+/** Generate multi-precision g-tag ladder for Nostr event publishing. */
+export declare function createGTagLadder(geohash: string, minPrecision?: number): string[][];
+/**
+ * Extract and parse g tags from a Nostr event's tag array.
+ * Invalid geohashes (containing non-base32 characters) are silently filtered out,
+ * since relay data is untrusted. Empty strings are also excluded.
+ */
+export declare function parseGTags(tags: string[][]): Array<{
+    geohash: string;
+    precision: number;
+}>;
+/** Return the highest-precision g tag from an event's tag array. */
+export declare function bestGeohash(tags: string[][]): string | undefined;
+/** Expand geohash into concentric rings of neighbours. */
+export declare function expandRings(hash: string, rings?: number): string[][];
+/** Generate a #g filter for Nostr REQ from coordinates and radius. */
+export declare function createGTagFilter(lat: number, lon: number, radiusMetres: number): {
+    '#g': string[];
+};
+/** Generate a #g filter from an existing geohash set. */
+export declare function createGTagFilterFromGeohashes(hashes: string[]): {
+    '#g': string[];
+};
+/** Convenience: encode + expand rings + flatten to filter. */
+export declare function nearbyFilter(lat: number, lon: number, options?: {
+    precision?: number;
+    rings?: number;
+}): {
+    '#g': string[];
+};
+//# sourceMappingURL=nostr.d.ts.map

package/dist/nostr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nostr.d.ts","sourceRoot":"","sources":["../src/nostr.ts"],"names":[],"mappings":"AAkBA,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,SAAI,GAAG,MAAM,EAAE,EAAE,CAM9E;AAID;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAI1F;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,GAAG,SAAS,CAIhE;AAID,0DAA0D;AAC1D,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,MAAM,EAAE,EAAE,CAqB/D;AAID,sEAAsE;AACtE,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,GACnB;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CASpB;AAED,yDAAyD;AACzD,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAElF;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAOpB"}

package/dist/nostr.js

@@ -0,0 +1,87 @@
+// geohash-kit/nostr — Nostr g-tag utilities
+import { encode, neighbours, radiusToPrecision } from './core.js';
+// --- Validation ---
+const BASE32 = '0123456789bcdefghjkmnpqrstuvwxyz';
+function isValidGeohash(hash) {
+    if (hash.length === 0)
+        return false;
+    for (const ch of hash) {
+        if (!BASE32.includes(ch))
+            return false;
+    }
+    return true;
+}
+// --- Publishing (event tags) ---
+/** Generate multi-precision g-tag ladder for Nostr event publishing. */
+export function createGTagLadder(geohash, minPrecision = 1) {
+    const tags = [];
+    for (let p = Math.max(1, minPrecision); p <= geohash.length; p++) {
+        tags.push(['g', geohash.slice(0, p)]);
+    }
+    return tags;
+}
+// --- Parsing ---
+/**
+ * Extract and parse g tags from a Nostr event's tag array.
+ * Invalid geohashes (containing non-base32 characters) are silently filtered out,
+ * since relay data is untrusted. Empty strings are also excluded.
+ */
+export function parseGTags(tags) {
+    return tags
+        .filter((t) => t[0] === 'g' && t[1] && isValidGeohash(t[1]))
+        .map((t) => ({ geohash: t[1], precision: t[1].length }));
+}
+/** Return the highest-precision g tag from an event's tag array. */
+export function bestGeohash(tags) {
+    const parsed = parseGTags(tags);
+    if (parsed.length === 0)
+        return undefined;
+    return parsed.reduce((best, curr) => curr.precision > best.precision ? curr : best).geohash;
+}
+// --- Ring expansion ---
+/** Expand geohash into concentric rings of neighbours. */
+export function expandRings(hash, rings = 1) {
+    const result = [[hash]];
+    const seen = new Set([hash]);
+    for (let ring = 1; ring <= rings; ring++) {
+        const prevRing = result[ring - 1];
+        const candidates = new Set();
+        for (const cell of prevRing) {
+            const n = neighbours(cell);
+            for (const adj of Object.values(n)) {
+                if (!seen.has(adj)) {
+                    candidates.add(adj);
+                }
+            }
+        }
+        const ringCells = Array.from(candidates);
+        for (const c of ringCells)
+            seen.add(c);
+        result.push(ringCells);
+    }
+    return result;
+}
+// --- Filter generation (subscribing) ---
+/** Generate a #g filter for Nostr REQ from coordinates and radius. */
+export function createGTagFilter(lat, lon, radiusMetres) {
+    const precision = radiusToPrecision(radiusMetres);
+    const hash = encode(lat, lon, precision);
+    // Expand one ring to cover cell boundaries
+    const rings = expandRings(hash, 1);
+    const allHashes = rings.flat();
+    return { '#g': [...new Set(allHashes)] };
+}
+/** Generate a #g filter from an existing geohash set. */
+export function createGTagFilterFromGeohashes(hashes) {
+    return { '#g': [...new Set(hashes)] };
+}
+/** Convenience: encode + expand rings + flatten to filter. */
+export function nearbyFilter(lat, lon, options) {
+    const precision = options?.precision ?? 5;
+    const ringCount = options?.rings ?? 1;
+    const hash = encode(lat, lon, precision);
+    const rings = expandRings(hash, ringCount);
+    const allHashes = rings.flat();
+    return { '#g': [...new Set(allHashes)] };
+}
+//# sourceMappingURL=nostr.js.map

package/dist/nostr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nostr.js","sourceRoot":"","sources":["../src/nostr.ts"],"names":[],"mappings":"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"}

package/llms-full.txt

@@ -0,0 +1,454 @@
+# geohash-kit — Full API Reference
+
+> Modern TypeScript geohash toolkit — encode, decode, cover polygons, and build Nostr filters.
+
+Zero dependencies. ESM-only. TypeScript native.
+
+Repository: https://github.com/TheCryptoDonkey/geohash-kit
+Licence: MIT
+
+## Install
+
+```
+npm install geohash-kit
+```
+
+## Imports
+
+```typescript
+// Barrel (everything)
+import { encode, polygonToGeohashes, createGTagLadder } from 'geohash-kit'
+
+// Subpath (tree-shakeable)
+import { encode, decode, bounds } from 'geohash-kit/core'
+import { polygonToGeohashes } from 'geohash-kit/coverage'
+import { createGTagLadder } from 'geohash-kit/nostr'
+```
+
+---
+
+## Types
+
+```typescript
+interface GeohashBounds {
+  minLat: number
+  maxLat: number
+  minLon: number
+  maxLon: number
+}
+
+type Direction = 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw'
+
+interface CoverageOptions {
+  minPrecision?: number    // default 1 — coarsest exploration level
+  maxPrecision?: number    // default 9 — finest exploration level
+  maxCells?: number        // default 500 — hard cap, triggers threshold tightening
+  mergeThreshold?: number  // default 1.0 — fraction of children to merge parent (0–1)
+}
+
+interface GeohashGeoJSON {
+  type: 'FeatureCollection'
+  features: Array<{
+    type: 'Feature'
+    geometry: { type: 'Polygon'; coordinates: [number, number][][] }
+    properties: { geohash: string; precision: number }
+  }>
+}
+
+interface GeoJSONPolygon {
+  type: 'Polygon'
+  coordinates: number[][][]
+}
+
+interface GeoJSONMultiPolygon {
+  type: 'MultiPolygon'
+  coordinates: number[][][][]
+}
+
+type PolygonInput = [number, number][] | GeoJSONPolygon | GeoJSONMultiPolygon
+```
+
+---
+
+## geohash-kit/core
+
+### encode(lat, lon, precision?)
+
+Encode latitude/longitude to a geohash string. Default precision 5 (~4.9km).
+
+```typescript
+encode(lat: number, lon: number, precision?: number): string
+
+encode(51.5074, -0.1278)     // 'gcpvj'
+encode(51.5074, -0.1278, 7)  // 'gcpvjbs'
+encode(0, 0, 5)              // 's0000'
+```
+
+### decode(hash)
+
+Decode a geohash to its centre point with error margins.
+
+```typescript
+decode(hash: string): { lat: number; lon: number; error: { lat: number; lon: number } }
+
+decode('gcpvj')  // { lat: 51.51, lon: -0.13, error: { lat: 0.02, lon: 0.02 } }
+```
+
+### bounds(hash)
+
+Get the bounding rectangle of a geohash cell.
+
+```typescript
+bounds(hash: string): GeohashBounds
+
+bounds('gcpvj')  // { minLat: 51.50, maxLat: 51.52, minLon: -0.15, maxLon: -0.10 }
+bounds('')       // { minLat: -90, maxLat: 90, minLon: -180, maxLon: 180 }
+```
+
+### children(hash)
+
+Get the 32 children of a geohash at the next precision level.
+
+```typescript
+children(hash: string): string[]
+
+children('g')   // ['g0', 'g1', ..., 'gz'] (32 entries)
+children('')    // ['0', '1', ..., 'z'] (32 top-level cells)
+```
+
+### neighbour(hash, direction)
+
+Get a single adjacent geohash cell in the given direction.
+
+```typescript
+neighbour(hash: string, direction: Direction): string
+
+neighbour('gcpvj', 'n')   // north neighbour at same precision
+neighbour('gcpvj', 'ne')  // north-east neighbour
+```
+
+### neighbours(hash)
+
+Get all 8 adjacent geohash cells.
+
+```typescript
+neighbours(hash: string): Record<Direction, string>
+
+neighbours('gcpvj')  // { n: '...', ne: '...', e: '...', se: '...', s: '...', sw: '...', w: '...', nw: '...' }
+```
+
+### contains(a, b)
+
+Check if two geohashes overlap (bidirectional prefix containment).
+
+```typescript
+contains(a: string, b: string): boolean
+
+contains('gcvd', 'gcvdn')   // true (gcvd contains gcvdn)
+contains('gcvdn', 'gcvd')   // true (gcvd contains gcvdn)
+contains('gcvdn', 'gcvdp')  // false (siblings)
+```
+
+### matchesAny(hash, candidates)
+
+Check if a geohash matches any candidate in a multi-precision set.
+
+```typescript
+matchesAny(hash: string, candidates: string[]): boolean
+
+matchesAny('gcvdn', ['gcpvj', 'gcvd', 'u10h'])  // true (gcvd is prefix)
+matchesAny('gcvdn', ['gcpvj', 'u10h'])           // false
+```
+
+### distance(hashA, hashB)
+
+Haversine distance in metres between centres of two geohash cells.
+
+```typescript
+distance(hashA: string, hashB: string): number
+
+distance('gcpvj', 'u09tu')  // ~340000 (London to Paris)
+distance('gcpvj', 'gcpvj')  // 0
+```
+
+### distanceFromCoords(lat1, lon1, lat2, lon2)
+
+Haversine distance in metres between two coordinate pairs.
+
+```typescript
+distanceFromCoords(lat1: number, lon1: number, lat2: number, lon2: number): number
+
+distanceFromCoords(51.5074, -0.1278, 48.8566, 2.3522)  // ~340000
+```
+
+### radiusToPrecision(metres)
+
+Optimal geohash precision for a given search radius in metres.
+
+```typescript
+radiusToPrecision(metres: number): number
+
+radiusToPrecision(5_000_000)  // 1
+radiusToPrecision(2_500)      // 5
+radiusToPrecision(80)         // 7
+radiusToPrecision(2)          // 9
+```
+
+### precisionToRadius(precision)
+
+Approximate cell radius in metres for a given precision level.
+
+```typescript
+precisionToRadius(precision: number): number
+
+precisionToRadius(1)  // 2_500_000
+precisionToRadius(5)  // 2_400
+precisionToRadius(9)  // 2.4
+```
+
+Precision table:
+
+| Precision | Cell width | Cell height | Approx. radius |
+|-----------|-----------|-------------|----------------|
+| 1 | ~5,000 km | ~5,000 km | ~2,500 km |
+| 2 | ~1,250 km | ~625 km | ~630 km |
+| 3 | ~156 km | ~156 km | ~78 km |
+| 4 | ~39.1 km | ~19.5 km | ~20 km |
+| 5 | ~4.89 km | ~4.89 km | ~2.4 km |
+| 6 | ~1.22 km | ~0.61 km | ~610 m |
+| 7 | ~153 m | ~153 m | ~76 m |
+| 8 | ~38.2 m | ~19.1 m | ~19 m |
+| 9 | ~4.77 m | ~4.77 m | ~2.4 m |
+
+---
+
+## geohash-kit/coverage
+
+### polygonToGeohashes(polygon, options?)
+
+Convert a polygon to a set of covering geohashes at variable precision.
+Uses adaptive threshold recursive subdivision with automatic threshold
+tightening to respect maxCells budget.
+
+```typescript
+polygonToGeohashes(
+  polygon: [number, number][] | GeoJSONPolygon | GeoJSONMultiPolygon,
+  options?: CoverageOptions
+): string[]
+
+// Cover central London (coordinate array)
+polygonToGeohashes([[-0.15, 51.50], [-0.10, 51.50], [-0.10, 51.52], [-0.15, 51.52]])
+
+// With options
+polygonToGeohashes(polygon, { maxCells: 100, mergeThreshold: 0.7 })
+
+// GeoJSON Polygon input
+polygonToGeohashes({
+  type: 'Polygon',
+  coordinates: [[[-0.15, 51.50], [-0.10, 51.50], [-0.10, 51.52], [-0.15, 51.52], [-0.15, 51.50]]]
+})
+
+// GeoJSON MultiPolygon input (results merged and deduplicated)
+polygonToGeohashes({
+  type: 'MultiPolygon',
+  coordinates: [
+    [[[-0.15, 51.50], [-0.10, 51.50], [-0.10, 51.52], [-0.15, 51.52], [-0.15, 51.50]]],
+    [[[-0.08, 51.50], [-0.03, 51.50], [-0.03, 51.52], [-0.08, 51.52], [-0.08, 51.50]]],
+  ]
+})
+```
+
+### geohashesToGeoJSON(hashes)
+
+Convert geohash set to GeoJSON FeatureCollection for map rendering.
+
+```typescript
+geohashesToGeoJSON(hashes: string[]): GeohashGeoJSON
+
+const geojson = geohashesToGeoJSON(['gcpvj', 'gcpvm'])
+// { type: 'FeatureCollection', features: [{ type: 'Feature', geometry: { type: 'Polygon', ... }, properties: { geohash: 'gcpvj', precision: 5 } }, ...] }
+```
+
+### geohashesToConvexHull(hashes)
+
+Reconstruct a convex polygon from a geohash set (Andrew's monotone chain).
+
+```typescript
+geohashesToConvexHull(hashes: string[]): [number, number][]
+
+const hull = geohashesToConvexHull(['gcpvj', 'gcpvm', 'gcpvn'])
+// [[lon, lat], [lon, lat], ...] — convex hull vertices
+```
+
+### deduplicateGeohashes(hashes, options?)
+
+Remove redundant ancestors from a multi-precision geohash set.
+Default mode merges only complete sibling sets (32/32). Pass `{ lossy: true }` to merge near-complete sets (≥30/32) for smaller output at the cost of slight boundary overshoot.
+
+```typescript
+deduplicateGeohashes(hashes: string[], options?: DeduplicateOptions): string[]
+
+deduplicateGeohashes(['gcp', 'gcpvj', 'gcpvm', 'u10'])  // ['gcp', 'u10']
+deduplicateGeohashes(hashes, { lossy: true })  // more aggressive merging
+```
+
+### pointInPolygon(point, polygon)
+
+Ray-casting point-in-polygon test.
+
+```typescript
+pointInPolygon(point: [number, number], polygon: [number, number][]): boolean
+
+pointInPolygon([5, 5], [[0, 0], [10, 0], [10, 10], [0, 10]])  // true
+```
+
+### boundsOverlapsPolygon(bounds, polygon)
+
+Check if a geohash cell's bounds overlap a polygon.
+
+```typescript
+boundsOverlapsPolygon(bounds: GeohashBounds, polygon: [number, number][]): boolean
+```
+
+### boundsFullyInsidePolygon(bounds, polygon)
+
+Check if a geohash cell is fully inside a polygon.
+
+```typescript
+boundsFullyInsidePolygon(bounds: GeohashBounds, polygon: [number, number][]): boolean
+```
+
+---
+
+## geohash-kit/nostr
+
+### createGTagLadder(geohash, minPrecision?)
+
+Generate multi-precision g-tag ladder for Nostr event publishing.
+
+```typescript
+createGTagLadder(geohash: string, minPrecision?: number): string[][]
+
+createGTagLadder('gcpvj')
+// [['g','g'], ['g','gc'], ['g','gcp'], ['g','gcpv'], ['g','gcpvj']]
+
+createGTagLadder('gcpvj', 3)
+// [['g','gcp'], ['g','gcpv'], ['g','gcpvj']]
+```
+
+### createGTagFilter(lat, lon, radiusMetres)
+
+Generate a #g filter for Nostr REQ from coordinates and radius.
+Encodes location, selects precision from radius, expands to neighbours.
+
+```typescript
+createGTagFilter(lat: number, lon: number, radiusMetres: number): { '#g': string[] }
+
+createGTagFilter(51.5074, -0.1278, 5000)
+// { '#g': ['gcpvj', 'gcpvm', 'gcpvn', ...] }
+```
+
+### createGTagFilterFromGeohashes(hashes)
+
+Generate a #g filter from an existing geohash set.
+
+```typescript
+createGTagFilterFromGeohashes(hashes: string[]): { '#g': string[] }
+
+createGTagFilterFromGeohashes(['gcpvj', 'gcpvm'])
+// { '#g': ['gcpvj', 'gcpvm'] }
+```
+
+### expandRings(hash, rings?)
+
+Expand geohash into concentric rings of neighbours.
+
+```typescript
+expandRings(hash: string, rings?: number): string[][]
+
+expandRings('gcpvj', 1)
+// [['gcpvj'], ['neighbour1', 'neighbour2', ..., 'neighbour8']]
+
+expandRings('gcpvj', 2)
+// [['gcpvj'], [8 ring-1 cells], [16 ring-2 cells]]
+```
+
+### nearbyFilter(lat, lon, options?)
+
+Convenience: encode + expand rings + flatten to filter.
+
+```typescript
+nearbyFilter(
+  lat: number,
+  lon: number,
+  options?: { precision?: number; rings?: number }
+): { '#g': string[] }
+
+nearbyFilter(51.5074, -0.1278)                        // precision 5, 1 ring
+nearbyFilter(51.5074, -0.1278, { precision: 3 })      // precision 3, 1 ring
+nearbyFilter(51.5074, -0.1278, { rings: 2 })           // precision 5, 2 rings
+```
+
+### parseGTags(tags)
+
+Extract and parse g tags from a Nostr event's tag array.
+
+```typescript
+parseGTags(tags: string[][]): Array<{ geohash: string; precision: number }>
+
+parseGTags([['g', 'gcpvj'], ['p', 'abc'], ['g', 'gcp']])
+// [{ geohash: 'gcpvj', precision: 5 }, { geohash: 'gcp', precision: 3 }]
+```
+
+### bestGeohash(tags)
+
+Return the highest-precision g tag from an event's tag array.
+
+```typescript
+bestGeohash(tags: string[][]): string | undefined
+
+bestGeohash([['g', 'g'], ['g', 'gc'], ['g', 'gcpvj']])  // 'gcpvj'
+bestGeohash([['p', 'abc']])                               // undefined
+```
+
+---
+
+## Nostr Usage Patterns
+
+### Publishing an event with location
+
+```typescript
+import { encode, createGTagLadder } from 'geohash-kit'
+
+const geohash = encode(51.5074, -0.1278, 6)  // 'gcpvjb'
+const tags = createGTagLadder(geohash)
+// Add tags to your Nostr event:
+// [['g','g'], ['g','gc'], ['g','gcp'], ['g','gcpv'], ['g','gcpvj'], ['g','gcpvjb']]
+```
+
+### Subscribing to nearby events
+
+```typescript
+import { createGTagFilter } from 'geohash-kit'
+
+const filter = createGTagFilter(51.5074, -0.1278, 5000)
+// Use in Nostr REQ: ['REQ', subId, { kinds: [1], ...filter }]
+```
+
+### Round-trip: publish → subscribe → match
+
+```typescript
+import { encode, createGTagLadder, createGTagFilter } from 'geohash-kit'
+
+// Publisher
+const hash = encode(51.5074, -0.1278, 6)
+const eventTags = createGTagLadder(hash)
+
+// Subscriber (nearby location)
+const filter = createGTagFilter(51.5080, -0.1270, 2000)
+
+// Match: at least one event tag value appears in the filter
+const tagValues = eventTags.map(t => t[1])
+const filterSet = new Set(filter['#g'])
+const matches = tagValues.some(v => filterSet.has(v))  // true
+```

package/llms.txt

@@ -0,0 +1,74 @@
+# geohash-kit
+
+> Modern TypeScript geohash toolkit — encode, decode, cover polygons, and build Nostr filters.
+
+Zero dependencies. ESM-only. Three subpath exports.
+
+## Install
+
+npm install geohash-kit
+
+## Subpath Exports
+
+### geohash-kit/core
+Basic geohash operations: encode, decode, bounds, neighbours, distance.
+
+- encode(lat, lon, precision?) → geohash string
+- decode(hash) → { lat, lon, error }
+- bounds(hash) → { minLat, maxLat, minLon, maxLon }
+- neighbours(hash) → { n, ne, e, se, s, sw, w, nw }
+- neighbour(hash, direction) → adjacent hash
+- children(hash) → 32 child hashes
+- contains(a, b) → boolean (prefix containment)
+- matchesAny(hash, candidates) → boolean
+- distance(hashA, hashB) → metres
+- distanceFromCoords(lat1, lon1, lat2, lon2) → metres
+- radiusToPrecision(metres) → precision level (1-9)
+- precisionToRadius(precision) → metres
+
+### geohash-kit/coverage
+Polygon-to-geohash coverage with adaptive threshold subdivision.
+
+- polygonToGeohashes(polygon, options?) → multi-precision hash set (accepts [lon,lat][], GeoJSON Polygon, or MultiPolygon)
+- geohashesToGeoJSON(hashes) → GeoJSON FeatureCollection
+- geohashesToConvexHull(hashes) → polygon vertices
+- deduplicateGeohashes(hashes, options?) → ancestor-free set ({ lossy: true } for 30/32 merges)
+- pointInPolygon(point, polygon) → boolean
+- boundsOverlapsPolygon(bounds, polygon) → boolean
+- boundsFullyInsidePolygon(bounds, polygon) → boolean
+
+### geohash-kit/nostr
+Nostr-specific g-tag utilities for event publishing and relay subscription.
+
+- createGTagLadder(geohash, minPrecision?) → string[][] (event tags)
+- createGTagFilter(lat, lon, radiusMetres) → { "#g": string[] }
+- createGTagFilterFromGeohashes(hashes) → { "#g": string[] }
+- expandRings(hash, rings?) → string[][] (concentric neighbour rings)
+- nearbyFilter(lat, lon, options?) → { "#g": string[] }
+- parseGTags(tags) → { geohash, precision }[]
+- bestGeohash(tags) → string | undefined
+
+## Quick Examples
+
+```typescript
+import { encode, neighbours, polygonToGeohashes, createGTagLadder, createGTagFilter } from 'geohash-kit'
+
+// Encode a location
+const hash = encode(51.5074, -0.1278) // 'gcpvj'
+
+// Get adjacent cells
+const adj = neighbours(hash) // { n: '...', ne: '...', ... }
+
+// Cover a polygon with geohashes
+const coverage = polygonToGeohashes([[-0.15, 51.50], [-0.10, 51.50], [-0.10, 51.52], [-0.15, 51.52]])
+
+// Generate Nostr event tags
+const tags = createGTagLadder(hash) // [['g','g'], ['g','gc'], ['g','gcp'], ['g','gcpv'], ['g','gcpvj']]
+
+// Generate Nostr subscription filter
+const filter = createGTagFilter(51.5074, -0.1278, 5000) // { '#g': ['gcpvj', 'gcpvm', ...] }
+```
+
+## Optional
+
+- llms-full.txt: Full API reference with all type signatures