@cyanheads/openstreetmap-mcp-server 0.2.0

package/dist/mcp-server/tools/definitions/openstreetmap-reverse.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openstreetmap-reverse.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/openstreetmap-reverse.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAMjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgJ/B,CAAC"}

package/dist/mcp-server/tools/definitions/openstreetmap-reverse.tool.js

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Reverse geocoding tool — converts coordinates to nearest address or place.
+ * @module mcp-server/tools/definitions/openstreetmap-reverse.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getNominatimService } from '../../../services/nominatim/nominatim-service.js';
+import { appendPlaceLines } from './openstreetmap-format.js';
+const ATTRIBUTION = 'Data © OpenStreetMap contributors, ODbL 1.0';
+export const openstreetmapReverse = tool('openstreetmap_reverse', {
+    title: 'Reverse geocode coordinates to an address',
+    description: 'Convert latitude/longitude coordinates to the nearest address or place name via Nominatim/OpenStreetMap. ' +
+        'Returns the closest matching OSM object at the given coordinates. ' +
+        'Note: Nominatim finds the nearest indexed OSM object — in dense areas this may differ from the address at the exact coordinate. ' +
+        'Use zoom=18 for building-level accuracy, lower zoom values for coarser resolution (e.g., zoom=10 for city-level).',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        lat: z.number().min(-90).max(90).describe('Latitude in WGS84 decimal degrees.'),
+        lon: z.number().min(-180).max(180).describe('Longitude in WGS84 decimal degrees.'),
+        zoom: z
+            .number()
+            .int()
+            .min(3)
+            .max(18)
+            .default(18)
+            .describe('Address detail level, roughly corresponding to map zoom. 18=building, 16=street, 14=neighbourhood, 12=town, 10=city, 8=county, 5=state, 3=country.'),
+        layer: z
+            .string()
+            .optional()
+            .describe('Restrict which OSM layer is matched. Comma-separated: address, poi, railway, natural, manmade. Default: address,poi.'),
+        extratags: z
+            .boolean()
+            .default(false)
+            .describe('Include extra OSM tags when available (phone, website, opening_hours, wikidata, etc.).'),
+        language: z
+            .string()
+            .optional()
+            .describe('Preferred language for the result (BCP 47 code or Accept-Language string).'),
+    }),
+    output: z.object({
+        result: z
+            .object({
+            place_id: z.number().describe('Nominatim internal place ID.'),
+            osm_type: z.enum(['node', 'way', 'relation']).optional().describe('OSM object type.'),
+            osm_id: z
+                .number()
+                .optional()
+                .describe('OSM object ID. Combine with osm_type for openstreetmap_lookup.'),
+            lat: z.string().describe('Latitude of the matched OSM object.'),
+            lon: z.string().describe('Longitude of the matched OSM object.'),
+            display_name: z.string().describe('Full human-readable address.'),
+            name: z.string().optional().describe('Feature name if the result is a named place.'),
+            category: z
+                .string()
+                .optional()
+                .describe('OSM feature category (e.g., "amenity", "building").'),
+            type: z.string().optional().describe('OSM feature type within category.'),
+            address: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe('Structured address. Keys vary by feature type. Common: house_number, road, suburb, city, state, postcode, country, country_code.'),
+            boundingbox: z
+                .tuple([z.string(), z.string(), z.string(), z.string()])
+                .optional()
+                .describe('Bounding box as [south, north, west, east] strings.'),
+            extratags: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe('Additional OSM tags (phone, website, opening_hours, wikidata). Present only when extratags was requested.'),
+        })
+            .describe('The closest matching OSM object at the given coordinates.'),
+        attribution: z.string().describe('Required data attribution.'),
+    }),
+    errors: [
+        {
+            reason: 'no_coverage',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Nominatim returns an error indicating no OSM data at the given coordinates (e.g., open ocean or unmapped territory).',
+            recovery: 'Verify the coordinates are correct. Try a lower zoom value to match at a coarser level (e.g., zoom=10 for city-level).',
+        },
+    ],
+    async handler(input, ctx) {
+        const service = getNominatimService();
+        const raw = await service.reverse({
+            lat: input.lat,
+            lon: input.lon,
+            zoom: input.zoom,
+            extratags: input.extratags,
+            ...(input.layer?.trim() ? { layer: input.layer } : {}),
+            ...(input.language?.trim() ? { language: input.language } : {}),
+        }, ctx);
+        // Nominatim returns HTTP 200 with {"error": "Unable to geocode"} for unmapped areas
+        if (raw.error) {
+            throw ctx.fail('no_coverage', `No OSM data at coordinates (${input.lat}, ${input.lon}): ${raw.error}`, { ...ctx.recoveryFor('no_coverage') });
+        }
+        ctx.log.info('Reverse geocode result', { display_name: raw.display_name });
+        return {
+            result: {
+                place_id: raw.place_id,
+                ...(raw.osm_type ? { osm_type: raw.osm_type } : {}),
+                ...(raw.osm_id !== undefined ? { osm_id: raw.osm_id } : {}),
+                lat: raw.lat,
+                lon: raw.lon,
+                display_name: raw.display_name,
+                ...(raw.name ? { name: raw.name } : {}),
+                ...(raw.category ? { category: raw.category } : {}),
+                ...(raw.type ? { type: raw.type } : {}),
+                ...(raw.address ? { address: raw.address } : {}),
+                ...(raw.boundingbox ? { boundingbox: raw.boundingbox } : {}),
+                ...(raw.extratags ? { extratags: raw.extratags } : {}),
+            },
+            attribution: ATTRIBUTION,
+        };
+    },
+    format: (result) => {
+        const r = result.result;
+        const lines = [];
+        if (r.name)
+            lines.push(`## ${r.name}`);
+        lines.push(`**Address:** ${r.display_name}`);
+        lines.push(`**Coordinates:** ${r.lat}, ${r.lon}`);
+        lines.push(`**Place ID:** ${r.place_id}`);
+        appendPlaceLines(lines, r);
+        lines.push('');
+        lines.push(`*${result.attribution}*`);
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=openstreetmap-reverse.tool.js.map

package/dist/mcp-server/tools/definitions/openstreetmap-reverse.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openstreetmap-reverse.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/openstreetmap-reverse.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE7D,MAAM,WAAW,GAAG,6CAA6C,CAAC;AAElE,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC,uBAAuB,EAAE;IAChE,KAAK,EAAE,2CAA2C;IAClD,WAAW,EACT,2GAA2G;QAC3G,oEAAoE;QACpE,kIAAkI;QAClI,mHAAmH;IACrH,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IAE9E,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,oCAAoC,CAAC;QAC/E,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,qCAAqC,CAAC;QAClF,IAAI,EAAE,CAAC;aACJ,MAAM,EAAE;aACR,GAAG,EAAE;aACL,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,EAAE,CAAC;aACP,OAAO,CAAC,EAAE,CAAC;aACX,QAAQ,CACP,oJAAoJ,CACrJ;QACH,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,sHAAsH,CACvH;QACH,SAAS,EAAE,CAAC;aACT,OAAO,EAAE;aACT,OAAO,CAAC,KAAK,CAAC;aACd,QAAQ,CACP,wFAAwF,CACzF;QACH,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,4EAA4E,CAAC;KAC1F,CAAC;IAEF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,MAAM,EAAE,CAAC;aACN,MAAM,CAAC;YACN,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;YAC7D,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;YACrF,MAAM,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,gEAAgE,CAAC;YAC7E,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;YAC/D,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;YAChE,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;YACjE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8CAA8C,CAAC;YACpF,QAAQ,EAAE,CAAC;iBACR,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,qDAAqD,CAAC;YAClE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;YACzE,OAAO,EAAE,CAAC;iBACP,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;iBAC9B,QAAQ,EAAE;iBACV,QAAQ,CACP,kIAAkI,CACnI;YACH,WAAW,EAAE,CAAC;iBACX,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;iBACvD,QAAQ,EAAE;iBACV,QAAQ,CAAC,qDAAqD,CAAC;YAClE,SAAS,EAAE,CAAC;iBACT,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;iBAC9B,QAAQ,EAAE;iBACV,QAAQ,CACP,2GAA2G,CAC5G;SACJ,CAAC;aACD,QAAQ,CAAC,2DAA2D,CAAC;QACxE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;KAC/D,CAAC;IAEF,MAAM,EAAE;QACN;YACE,MAAM,EAAE,aAAa;YACrB,IAAI,EAAE,gBAAgB,CAAC,QAAQ;YAC/B,IAAI,EAAE,sHAAsH;YAC5H,QAAQ,EACN,wHAAwH;SAC3H;KACF;IAED,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,MAAM,OAAO,GAAG,mBAAmB,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,OAAO,CAC/B;YACE,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtD,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChE,EACD,GAAG,CACJ,CAAC;QAEF,oFAAoF;QACpF,IAAI,GAAG,CAAC,KAAK,EAAE,CAAC;YACd,MAAM,GAAG,CAAC,IAAI,CACZ,aAAa,EACb,+BAA+B,KAAK,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,EACvE,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,aAAa,CAAC,EAAE,CACtC,CAAC;QACJ,CAAC;QAED,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,wBAAwB,EAAE,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC;QAE3E,OAAO;YACL,MAAM,EAAE;gBACN,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnD,GAAG,CAAC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3D,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,GAAG,EAAE,GAAG,CAAC,GAAG;gBACZ,YAAY,EAAE,GAAG,CAAC,YAAY;gBAC9B,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAChD,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC5D,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACvD;YACD,WAAW,EAAE,WAAW;SACzB,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACjB,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC;QACxB,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAClD,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC1C,gBAAgB,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAC3B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,WAAW,GAAG,CAAC,CAAC;QACtC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/openstreetmap-tag-input.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Shared tag input validation and resolution for Overpass convenience tools.
+ * @module mcp-server/tools/definitions/openstreetmap-tag-input
+ */
+/** Resolved tag key/value pair extracted from amenity shortcut or explicit tag_key/tag_value. */
+export type ResolvedTag = {
+    tagKey: string;
+    tagValue: string;
+};
+/**
+ * Validate and resolve the mutually-exclusive amenity / tag_key+tag_value input pattern.
+ * Throws an error string on invalid input; callers translate it to ctx.fail.
+ */
+export declare function resolveTagInput(input: {
+    amenity?: string | undefined;
+    tag_key?: string | undefined;
+    tag_value?: string | undefined;
+}): ResolvedTag | {
+    error: 'both' | 'neither';
+};
+//# sourceMappingURL=openstreetmap-tag-input.d.ts.map

package/dist/mcp-server/tools/definitions/openstreetmap-tag-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openstreetmap-tag-input.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/openstreetmap-tag-input.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,iGAAiG;AACjG,MAAM,MAAM,WAAW,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC,GAAG,WAAW,GAAG;IAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAY9C"}

package/dist/mcp-server/tools/definitions/openstreetmap-tag-input.js

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Shared tag input validation and resolution for Overpass convenience tools.
+ * @module mcp-server/tools/definitions/openstreetmap-tag-input
+ */
+/**
+ * Validate and resolve the mutually-exclusive amenity / tag_key+tag_value input pattern.
+ * Throws an error string on invalid input; callers translate it to ctx.fail.
+ */
+export function resolveTagInput(input) {
+    const hasAmenity = Boolean(input.amenity?.trim());
+    const hasTagKey = Boolean(input.tag_key?.trim());
+    const hasTagValue = Boolean(input.tag_value?.trim());
+    if (hasAmenity && (hasTagKey || hasTagValue))
+        return { error: 'both' };
+    if (!hasAmenity && !hasTagKey)
+        return { error: 'neither' };
+    return {
+        tagKey: hasAmenity ? 'amenity' : (input.tag_key ?? ''),
+        tagValue: hasAmenity ? (input.amenity ?? '') : (input.tag_value ?? ''),
+    };
+}
+//# sourceMappingURL=openstreetmap-tag-input.js.map

package/dist/mcp-server/tools/definitions/openstreetmap-tag-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openstreetmap-tag-input.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/openstreetmap-tag-input.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAI/B;IACC,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IACjD,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAErD,IAAI,UAAU,IAAI,CAAC,SAAS,IAAI,WAAW,CAAC;QAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IACvE,IAAI,CAAC,UAAU,IAAI,CAAC,SAAS;QAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAE3D,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;QACtD,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,IAAI,EAAE,CAAC;KACvE,CAAC;AACJ,CAAC"}

package/dist/services/nominatim/nominatim-service.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Nominatim API client with rate limiting, retry, and session caching.
+ * @module services/nominatim/nominatim-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { NominatimLookupParams, NominatimPlace, NominatimReverseParams, NominatimSearchParams } from './types.js';
+export declare class NominatimService {
+    private lastRequestTime;
+    constructor(_config: AppConfig, _storage: StorageService);
+    /** Enforce the 1 req/sec rate limit. */
+    private throttle;
+    private userAgent;
+    private baseUrl;
+    private buildCacheKey;
+    private fetchJson;
+    search(params: NominatimSearchParams, ctx: Context): Promise<NominatimPlace[]>;
+    reverse(params: NominatimReverseParams, ctx: Context): Promise<NominatimPlace>;
+    lookup(params: NominatimLookupParams, ctx: Context): Promise<NominatimPlace[]>;
+}
+export declare function initNominatimService(config: AppConfig, storage: StorageService): void;
+export declare function getNominatimService(): NominatimService;
+//# sourceMappingURL=nominatim-service.d.ts.map

package/dist/services/nominatim/nominatim-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nominatim-service.d.ts","sourceRoot":"","sources":["../../../src/services/nominatim/nominatim-service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAIrE,OAAO,KAAK,EACV,qBAAqB,EACrB,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAQpB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,eAAe,CAAK;gBAGhB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc;IAExD,wCAAwC;YAC1B,QAAQ;IAStB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,aAAa;YAKP,SAAS;IAuCjB,MAAM,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA0C9E,OAAO,CAAC,MAAM,EAAE,sBAAsB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC;IAiC9E,MAAM,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;CA6BrF;AAMD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAErF;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAKtD"}

package/dist/services/nominatim/nominatim-service.js

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview Nominatim API client with rate limiting, retry, and session caching.
+ * @module services/nominatim/nominatim-service
+ */
+import { createHash } from 'node:crypto';
+import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { fetchWithTimeout, withRetry } from '@cyanheads/mcp-ts-core/utils';
+import { getServerConfig } from '../../config/server-config.js';
+/** Cache TTL: 60 minutes (geocoding results rarely change within a session). */
+const CACHE_TTL_SECONDS = 3600;
+/** Nominatim enforces a strict 1 req/sec limit. */
+const MIN_REQUEST_INTERVAL_MS = 1050;
+export class NominatimService {
+    lastRequestTime = 0;
+    // config and storage reserved for future use (private instance auth, custom storage)
+    constructor(_config, _storage) { }
+    /** Enforce the 1 req/sec rate limit. */
+    async throttle() {
+        const now = Date.now();
+        const elapsed = now - this.lastRequestTime;
+        if (elapsed < MIN_REQUEST_INTERVAL_MS) {
+            await new Promise((resolve) => setTimeout(resolve, MIN_REQUEST_INTERVAL_MS - elapsed));
+        }
+        this.lastRequestTime = Date.now();
+    }
+    userAgent() {
+        return getServerConfig().nominatimUserAgent;
+    }
+    baseUrl() {
+        return getServerConfig().nominatimBaseUrl;
+    }
+    buildCacheKey(endpoint, params) {
+        const hash = createHash('sha256').update(JSON.stringify(params)).digest('hex').slice(0, 16);
+        return `nominatim/${endpoint}/${hash}`;
+    }
+    async fetchJson(path, params, ctx) {
+        const url = new URL(path, this.baseUrl());
+        url.searchParams.set('format', 'jsonv2');
+        url.searchParams.set('addressdetails', '1');
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined && value !== '') {
+                url.searchParams.set(key, value);
+            }
+        }
+        await this.throttle();
+        const response = await fetchWithTimeout(url.toString(), 30_000, ctx, {
+            headers: {
+                'User-Agent': this.userAgent(),
+                Accept: 'application/json',
+            },
+            signal: ctx.signal,
+        });
+        const text = await response.text();
+        if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+            throw serviceUnavailable('Nominatim returned an HTML error page — likely rate-limited or unavailable.');
+        }
+        return JSON.parse(text);
+    }
+    async search(params, ctx) {
+        const cacheKey = this.buildCacheKey('search', params);
+        const cached = await ctx.state.get(cacheKey);
+        if (cached != null) {
+            ctx.log.debug('Nominatim search cache hit', { cacheKey });
+            return cached;
+        }
+        const queryParams = {};
+        const setIfTruthy = (key, val) => {
+            if (val)
+                queryParams[key] = String(val);
+        };
+        setIfTruthy('q', params.q);
+        setIfTruthy('street', params.street);
+        setIfTruthy('city', params.city);
+        setIfTruthy('county', params.county);
+        setIfTruthy('state', params.state);
+        setIfTruthy('country', params.country);
+        setIfTruthy('postalcode', params.postalcode);
+        setIfTruthy('limit', params.limit);
+        setIfTruthy('countrycodes', params.countrycodes);
+        setIfTruthy('layer', params.layer);
+        setIfTruthy('featuretype', params.featureType);
+        if (params.extratags)
+            queryParams.extratags = '1';
+        setIfTruthy('accept_language', params.language);
+        ctx.log.info('Nominatim search', { params });
+        const results = await withRetry(() => this.fetchJson('/search', queryParams, ctx), {
+            operation: 'nominatim.search',
+            context: ctx,
+            baseDelayMs: 1100,
+            signal: ctx.signal,
+        });
+        await ctx.state.set(cacheKey, results, { ttl: CACHE_TTL_SECONDS });
+        return results;
+    }
+    async reverse(params, ctx) {
+        const cacheKey = this.buildCacheKey('reverse', params);
+        const cached = await ctx.state.get(cacheKey);
+        if (cached != null) {
+            ctx.log.debug('Nominatim reverse cache hit', { cacheKey });
+            return cached;
+        }
+        const queryParams = {
+            lat: String(params.lat),
+            lon: String(params.lon),
+        };
+        if (params.zoom !== undefined)
+            queryParams.zoom = String(params.zoom);
+        if (params.layer)
+            queryParams.layer = params.layer;
+        if (params.extratags)
+            queryParams.extratags = '1';
+        if (params.language)
+            queryParams.accept_language = params.language;
+        ctx.log.info('Nominatim reverse', { lat: params.lat, lon: params.lon });
+        const result = await withRetry(() => this.fetchJson('/reverse', queryParams, ctx), {
+            operation: 'nominatim.reverse',
+            context: ctx,
+            baseDelayMs: 1100,
+            signal: ctx.signal,
+        });
+        await ctx.state.set(cacheKey, result, { ttl: CACHE_TTL_SECONDS });
+        return result;
+    }
+    async lookup(params, ctx) {
+        const cacheKey = this.buildCacheKey('lookup', params);
+        const cached = await ctx.state.get(cacheKey);
+        if (cached != null) {
+            ctx.log.debug('Nominatim lookup cache hit', { cacheKey });
+            return cached;
+        }
+        const queryParams = {
+            osm_ids: params.osm_ids.join(','),
+        };
+        if (params.extratags)
+            queryParams.extratags = '1';
+        if (params.language)
+            queryParams.accept_language = params.language;
+        ctx.log.info('Nominatim lookup', { osm_ids: params.osm_ids });
+        const results = await withRetry(() => this.fetchJson('/lookup', queryParams, ctx), {
+            operation: 'nominatim.lookup',
+            context: ctx,
+            baseDelayMs: 1100,
+            signal: ctx.signal,
+        });
+        await ctx.state.set(cacheKey, results, { ttl: CACHE_TTL_SECONDS });
+        return results;
+    }
+}
+// --- Init/accessor pattern ---
+let _service;
+export function initNominatimService(config, storage) {
+    _service = new NominatimService(config, storage);
+}
+export function getNominatimService() {
+    if (!_service) {
+        throw new Error('NominatimService not initialized — call initNominatimService() in setup()');
+    }
+    return _service;
+}
+//# sourceMappingURL=nominatim-service.js.map

package/dist/services/nominatim/nominatim-service.js.map

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

package/dist/services/nominatim/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Types for the Nominatim API responses and domain models.
+ * @module services/nominatim/types
+ */
+/** Raw Nominatim place result (jsonv2 format). Fields vary by feature type. */
+export type NominatimPlace = {
+    place_id: number;
+    osm_type?: 'node' | 'way' | 'relation';
+    osm_id?: number;
+    lat: string;
+    lon: string;
+    display_name: string;
+    name?: string;
+    category?: string;
+    type?: string;
+    place_rank?: number;
+    importance?: number;
+    addresstype?: string;
+    address?: Record<string, string>;
+    boundingbox?: [string, string, string, string];
+    extratags?: Record<string, string>;
+    error?: string;
+};
+/** Parameters for the Nominatim /search endpoint. */
+export type NominatimSearchParams = {
+    q?: string;
+    street?: string;
+    city?: string;
+    county?: string;
+    state?: string;
+    country?: string;
+    postalcode?: string;
+    limit?: number;
+    countrycodes?: string;
+    layer?: string;
+    featureType?: string;
+    extratags?: boolean;
+    language?: string;
+};
+/** Parameters for the Nominatim /reverse endpoint. */
+export type NominatimReverseParams = {
+    lat: number;
+    lon: number;
+    zoom?: number;
+    layer?: string;
+    extratags?: boolean;
+    language?: string;
+};
+/** Parameters for the Nominatim /lookup endpoint. */
+export type NominatimLookupParams = {
+    osm_ids: string[];
+    extratags?: boolean;
+    language?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/services/nominatim/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/nominatim/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,qDAAqD;AACrD,MAAM,MAAM,qBAAqB,GAAG;IAClC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,sDAAsD;AACtD,MAAM,MAAM,sBAAsB,GAAG;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,qDAAqD;AACrD,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC"}

package/dist/services/nominatim/types.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Types for the Nominatim API responses and domain models.
+ * @module services/nominatim/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/nominatim/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/nominatim/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/services/overpass/overpass-service.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview Overpass API client with retry, session caching, and QL query builders.
+ * @module services/overpass/overpass-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { OverpassAroundParams, OverpassBboxParams, OverpassElement, OverpassPoi, OverpassResponse } from './types.js';
+export declare class OverpassService {
+    constructor(_config: AppConfig, _storage: StorageService);
+    private endpoint;
+    private buildCacheKey;
+    /** Build an around-filter Overpass QL query. */
+    buildAroundQuery(params: OverpassAroundParams): string;
+    /** Build a bounding-box Overpass QL query. */
+    buildBboxQuery(params: OverpassBboxParams): string;
+    private executeQuery;
+    /** Execute a generated or raw Overpass QL query and return raw elements. */
+    query(ql: string, ctx: Context): Promise<OverpassResponse>;
+    /** Normalize Overpass elements into POI-friendly shape. */
+    normalizeElements(elements: OverpassElement[]): OverpassPoi[];
+}
+export declare function initOverpassService(config: AppConfig, storage: StorageService): void;
+export declare function getOverpassService(): OverpassService;
+//# sourceMappingURL=overpass-service.d.ts.map

package/dist/services/overpass/overpass-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overpass-service.d.ts","sourceRoot":"","sources":["../../../src/services/overpass/overpass-service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAIrE,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAWpB,qBAAa,eAAe;gBAEd,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc;IAExD,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,aAAa;IAKrB,gDAAgD;IAChD,gBAAgB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM;IActD,8CAA8C;IAC9C,cAAc,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM;YAepC,YAAY;IA6E1B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAK1D,2DAA2D;IAC3D,iBAAiB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,WAAW,EAAE;CAe9D;AAMD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAEpF;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAKpD"}

package/dist/services/overpass/overpass-service.js

@@ -0,0 +1,146 @@
+/**
+ * @fileoverview Overpass API client with retry, session caching, and QL query builders.
+ * @module services/overpass/overpass-service
+ */
+import { createHash } from 'node:crypto';
+import { serviceUnavailable, timeout as timeoutError } from '@cyanheads/mcp-ts-core/errors';
+import { withRetry } from '@cyanheads/mcp-ts-core/utils';
+import { getServerConfig } from '../../config/server-config.js';
+/** Cache TTL for Overpass results: 10 minutes (more volatile than geocoding). */
+const CACHE_TTL_SECONDS = 600;
+/** Overpass timeout error messages that indicate query-level timeout. */
+const OVERPASS_TIMEOUT_PATTERN = /runtime error|query timed out|timed out/i;
+/** Overpass out-of-memory error patterns. */
+const OVERPASS_OOM_PATTERN = /out of memory|query run out/i;
+export class OverpassService {
+    // config and storage reserved for future use (private instance auth, custom storage)
+    constructor(_config, _storage) { }
+    endpoint() {
+        return getServerConfig().overpassBaseUrl;
+    }
+    buildCacheKey(query) {
+        const hash = createHash('sha256').update(query).digest('hex').slice(0, 16);
+        return `overpass/${hash}`;
+    }
+    /** Build an around-filter Overpass QL query. */
+    buildAroundQuery(params) {
+        const { lat, lon, radiusMeters, tagKey, tagValue, elementTypes, timeoutSeconds } = params;
+        const filter = `(around:${radiusMeters},${lat},${lon})`;
+        const tagFilter = `["${tagKey}"="${tagValue}"]`;
+        const lines = [
+            `[out:json][timeout:${timeoutSeconds}];`,
+            '(',
+            ...elementTypes.map((t) => `  ${t}${tagFilter}${filter};`),
+            ');',
+            'out center tags;',
+        ];
+        return lines.join('\n');
+    }
+    /** Build a bounding-box Overpass QL query. */
+    buildBboxQuery(params) {
+        const { south, west, north, east, tagKey, tagValue, elementTypes, timeoutSeconds } = params;
+        // Overpass bbox order: south,west,north,east (latitude-first)
+        const filter = `(${south},${west},${north},${east})`;
+        const tagFilter = `["${tagKey}"="${tagValue}"]`;
+        const lines = [
+            `[out:json][timeout:${timeoutSeconds}];`,
+            '(',
+            ...elementTypes.map((t) => `  ${t}${tagFilter}${filter};`),
+            ');',
+            'out center tags;',
+        ];
+        return lines.join('\n');
+    }
+    async executeQuery(query, ctx) {
+        const cacheKey = this.buildCacheKey(query);
+        const cached = await ctx.state.get(cacheKey);
+        if (cached !== null) {
+            ctx.log.debug('Overpass cache hit');
+            return cached;
+        }
+        const result = await withRetry(async () => {
+            const response = await fetch(this.endpoint(), {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    'User-Agent': getServerConfig().nominatimUserAgent,
+                },
+                body: `data=${encodeURIComponent(query)}`,
+                signal: ctx.signal,
+            });
+            if (response.status === 429) {
+                throw serviceUnavailable('Overpass API returned HTTP 429 — all query slots occupied.', {
+                    reason: 'rate_limited',
+                });
+            }
+            if (response.status === 400) {
+                const body = await response.text();
+                throw serviceUnavailable(`Overpass API returned HTTP 400 — malformed query syntax. ${body.slice(0, 200)}`, { reason: 'query_error' });
+            }
+            if (!response.ok) {
+                throw serviceUnavailable(`Overpass API returned HTTP ${response.status}`, {
+                    status: response.status,
+                });
+            }
+            const text = await response.text();
+            if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+                throw serviceUnavailable('Overpass returned an HTML page instead of JSON — likely rate-limited.');
+            }
+            const data = JSON.parse(text);
+            // Detect runtime errors embedded in JSON response
+            if (data.remark) {
+                if (OVERPASS_TIMEOUT_PATTERN.test(data.remark)) {
+                    throw timeoutError(`Overpass query timed out: ${data.remark}`, {
+                        reason: 'query_timeout',
+                    });
+                }
+                if (OVERPASS_OOM_PATTERN.test(data.remark)) {
+                    throw serviceUnavailable(`Overpass ran out of memory: ${data.remark}`, {
+                        reason: 'result_too_large',
+                    });
+                }
+            }
+            return data;
+        }, {
+            operation: 'overpass.query',
+            context: ctx,
+            baseDelayMs: 2000,
+            signal: ctx.signal,
+        });
+        await ctx.state.set(cacheKey, result, { ttl: CACHE_TTL_SECONDS });
+        return result;
+    }
+    /** Execute a generated or raw Overpass QL query and return raw elements. */
+    query(ql, ctx) {
+        ctx.log.info('Overpass query', { queryLength: ql.length });
+        return this.executeQuery(ql, ctx);
+    }
+    /** Normalize Overpass elements into POI-friendly shape. */
+    normalizeElements(elements) {
+        return elements.map((el) => {
+            const lat = el.type === 'node' ? el.lat : el.center?.lat;
+            const lon = el.type === 'node' ? el.lon : el.center?.lon;
+            const tags = el.tags ?? {};
+            return {
+                osm_type: el.type,
+                osm_id: el.id,
+                ...(lat !== undefined && { lat }),
+                ...(lon !== undefined && { lon }),
+                ...(tags.name ? { name: tags.name } : {}),
+                tags,
+            };
+        });
+    }
+}
+// --- Init/accessor pattern ---
+let _service;
+export function initOverpassService(config, storage) {
+    _service = new OverpassService(config, storage);
+}
+export function getOverpassService() {
+    if (!_service) {
+        throw new Error('OverpassService not initialized — call initOverpassService() in setup()');
+    }
+    return _service;
+}
+//# sourceMappingURL=overpass-service.js.map